github.com/containerd/containerd@v22.0.0-20200918172823-438c87b8e050+incompatible/docs/namespaces.md (about)

     1  # containerd Namespaces and Multi-Tenancy
     2  
     3  containerd offers a fully namespaced API so multiple consumers can all use a single containerd instance without conflicting with one another.
     4  Namespaces allow multi-tenancy within a single daemon. This removes the need for the common pattern of using nested containers to achieve this separation.
     5  Consumers are able to have containers with the same names but with settings and/or configurations that vary drastically.
     6  For example, system or infrastructure level containers can be hidden in one namespace while user level containers are kept in another.
     7  Underlying image content is still shared via content addresses but image names and metadata are separate per namespace.
     8  
     9  It is important to note that namespaces, as implemented, is an administrative construct that is not meant to be used as a security feature.
    10  It is trivial for clients to switch namespaces.
    11  
    12  ## Who specifies the namespace?
    13  
    14  The client specifies the namespace via the `context`.
    15  There is a `github.com/containerd/containerd/namespaces` package that allows a user to get and set the namespace on a context.
    16  
    17  ```go
    18  // set a namespace
    19  ctx := namespaces.WithNamespace(context.Background(), "my-namespace")
    20  
    21  // get the namespace
    22  ns, ok := namespaces.Namespace(ctx)
    23  ```
    24  
    25  Because the client calls containerd's gRPC API to interact with the daemon, all API calls require a context with a namespace set.
    26  
    27  ## How low level is the implementation?
    28  
    29  Namespaces are passed through the containerd API to the underlying plugins providing functionality.
    30  Plugins must be written to take namespaces into account.
    31  Filesystem paths, IDs, and other system level resources must be namespaced for a plugin to work properly.
    32  
    33  ## How does multi-tenancy work?
    34  
    35  Simply create a new `context` and set your application's namespace on the `context`.
    36  Make sure to use a unique namespace for applications that does not conflict with existing namespaces. The namespaces
    37  API, or the `ctr namespaces` client command, can be used to query/list and create new namespaces.
    38  
    39  ```go
    40  ctx := context.Background()
    41  
    42  var (
    43  	docker = namespaces.WithNamespace(ctx, "docker")
    44  	vmware = namespaces.WithNamespace(ctx, "vmware")
    45  	ecs = namespaces.WithNamespace(ctx, "aws-ecs")
    46  	cri = namespaces.WithNamespace(ctx, "cri")
    47  )
    48  ```
    49  
    50  ## Namespace Labels
    51  
    52  Namespaces can have a list of labels associated with the namespace. This can be useful for associating metadata with a particular namespace.
    53  Labels can also be used to configure the defaults for containerd, for example:
    54  
    55  ```bash
    56  > sudo ctr namespaces label k8s.io containerd.io/defaults/snapshotter=btrfs
    57  > sudo ctr namespaces label k8s.io containerd.io/defaults/runtime=testRuntime
    58  ```
    59  
    60  This will set the default snapshotter as `btrfs` and runtime as `testRuntime`.
    61  Note that currently only these two labels are used to configure the defaults and labels of `default` namespace are not considered for the same.
    62  
    63  ## Inspecting Namespaces
    64  
    65  If we need to inspect containers, images, or other resources in various namespaces the `ctr` tool allows you to do this.
    66  Simply set the `--namespace,-n` flag on `ctr` to change the namespace. If you do not provide a namespace, `ctr` client commands
    67  will all use the default namespace, which is simply named "`default`".
    68  
    69  ```bash
    70  > sudo ctr -n docker tasks
    71  > sudo ctr -n cri tasks
    72  ```
    73  
    74  You can also use the `CONTAINERD_NAMESPACE` environment variable to specify the default namespace to use for
    75  any of the `ctr` client commands.