Merge pull request #620 from MBishop17/namespaces

Namespaces
2026-09-25 12:38:05 +00:00 · 2018-08-21 15:43:23 -07:00
parent 161f84bd34 b87a7424b0
commit 1988c247e4
9 changed files with 85 additions and 32 deletions
@@ -23,7 +23,7 @@ Add SSL certificates to either projects, namespaces, or both. A project scoped c

    - **Available to all namespaces in this project:** The certificate is available for any deployment in any namespaces in the project.

-    - **Available to a single namespace:** The certificate is only available for the deployments in one namespace. If you choose this option, select a **Namespace** from the drop-down list or click **Add to a new namespace** to add the certificate to a namespace you create on the fly.
+    - **Available to a single namespace:** The certificate is only available for the deployments in one [namespace]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#namespaces). If you choose this option, select a **Namespace** from the drop-down list or click **Add to a new namespace** to add the certificate to a namespace you create on the fly.

 1. From **Private Key**, either copy and paste your certificate's private key into the text box (include the header and footer), or click **Read from a file** to browse to the private key on your file system. If possible, we recommend using **Read from a file** to reduce likelihood of error.

@@ -10,8 +10,8 @@ While most types of Kubernetes secrets store sensitive information, [ConfigMaps]

 ConfigMaps accept key value pairs in common string formats, like config files or JSON blobs. After you upload a config map, any workload can reference it as either an environment variable or a volume mount.

->**Note:** ConfigMaps are only available within namespaces and not projects.
-
+>**Note:** ConfigMaps are only available within [namespaces]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#namespaces) and not [projects]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#projects).
+({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#namespaces)
 ConfigMaps store general configuration information for an application, such as configuration files, command-line arguments, environment variables, etc. ConfigMaps accept key value pairs in common string formats, like config files or JSON blobs. Add ConfigMaps to your Rancher workspaces so that you can add them to your workloads later. For more information on ConfigMaps, see the official [Kubernetes Documentation: Using ConfigMap](https://kubernetes-v1-4.github.io/docs/user-guide/configmap/).

 >**Note:** ConfigMaps can only be applied to namespaces and not projects.
@@ -13,7 +13,7 @@ Ingress can be added for workloads to provide load balancing, SSL termination an

 1. Enter a **Name** for the ingress.

-1. Select an existing **Namespace** from the drop-down list. Alternatively, you can create a new namespace on the fly by clicking **Add to a new namespace**.
+1. Select an existing **Namespace** from the drop-down list. Alternatively, you can create a new [namespace]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#namespaces) on the fly by clicking **Add to a new namespace**.

 1. Create ingress forwarding **Rules**.

@@ -9,19 +9,31 @@ aliases:

 ## Projects

-_Projects_ are objects that captures a set of policies for a set of namespaces. They are a new concept introduced by Rancher, and they are not a native Kubernetes construct.
+_Projects_ are organizational objects introduced in Rancher that ease the administrative burden of your cluster. You can use projects to support multi-tenancy. 
+
+Projects provide an extra level of organization in your Kubernetes clusters beyond [namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/). In terms of hierarchy:
+
+- Clusters contain projects.
+- Projects contain namespaces.
+
+Within Rancher, projects allow you manage multiple namespaces as a single entity. In the base version of Kubernetes, which does not include projects, features like role-based access rights or cluster resources are assigned to individual namespaces. In clusters where multiple namespaces require the same set of access rights, assigning these rights to each individual namespace can become tedious. Even though all namespaces require the same rights, there's no way to apply those rights to all of your namespaces in a single action. You'd have to repetitively assign these rights to each namespace!
+
+Rancher projects resolve this issue by allowing you to apply resources and access rights at the project level. Each namespace in the project then inherits these resources and policies, so you only have to assign them to the project once, rather than assigning them to each namespace.

 You can use projects to perform actions like:

- Assigning users to access to a group of namespaces (i.e., [project membership]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/project-members))
- Assigning users specific roles in a project. A role can be owner, member, read-only, or [custom]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/). Policies include Kubernetes Role-Based Access Control (RBAC) policies.
- Assigning Pod Security Policies.
+- Assign users access to a group of namespaces (i.e., [project membership]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/project-members)).
+- Assign users specific roles in a project. A role can be owner, member, read-only, or [custom]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/). 
+- Assign resources to the project.
+- Assign Pod Security Policies.
+

 When you create a cluster, two project are automatically created within it:

 - [Default Project](#default-project)
 - [System Project](#system-project) 

+
 ### Default Project

 When you provision a cluster, it automatically creates a `default` project for the cluster. This is a project you can use to get started with your cluster, but you can always delete it and replace it with projects that have more descriptive names.
@@ -48,24 +60,18 @@ The `system` project:
 >
 >The `system` project overrides the Project Network Isolation option so that it can communicate with other projects, collect logs, and check health. 

-## Authorization
+### Authorization

 Non-administrative users are only authorized for project access after an administrator explicitly adds them to the project's **Members** tab.

 >**Exception:**
 > Non-administrative users can access projects that they create themselves.

-## Pod Security Policies
+### Pod Security Policies

 Rancher extends Kubernetes to allow the application of [Pod Security Policies](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) at the project level in addition to the cluster level. However, as a best practice, we recommend applying Pod Security Policies at the cluster level.

-## Namespaces
-
-Kubernetes resources belong to specific namespaces. Rancher 2.0 relies on namespaces to isolate resources among users and apps. When the user deploys an app from the catalog, for example, he can choose to deploy that app into its own namespace, so that resource names in one app will not conflict with resource names in another. Namespaces must be globally unique. It is often difficult for users to pick unique namespace names. Rancher therefore encourages the pattern where users work with projects, and the system generates unique namespace names automatically.
-
-For more information, see the [Kubernetes Namespaces Documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/).
-
-## Creating Projects
+### Creating Projects

 1. From the **Global** view, choose **Clusters** from the main menu. From the **Clusters** page, open the cluster from which you want to create a project.

@@ -75,9 +81,9 @@ For more information, see the [Kubernetes Namespaces Documentation](https://kube

 1. **Optional:** Select a **Pod Security Policy**. Assigning a PSP to a project will:

-  - Override the cluster's default PSP.
-  - Apply the PSP to the project.
-  - Apply the PSP to any namespaces you add to the project later.
+    - Override the cluster's default PSP.
+    - Apply the PSP to the project.
+    - Apply the PSP to any namespaces you add to the project later.

    >**Note:** This option is only available if you've already created a Pod Security Policy. For instruction, see [Creating Pod Security Policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/).

@@ -101,14 +107,13 @@ For more information, see the [Kubernetes Namespaces Documentation](https://kube

    1. To add more members, repeat substeps a—c.

-
 1. Click **Create**.

 **Result:** Your project is created. You can view it from the cluster's **Projects/Namespaces** view.

-## Switching Projects
+## Switching Clusters/Projects

-To switch between clusters, use the **Global** drop-down available in the main menu.
+To switch between clusters and projects, use the **Global** drop-down available in the main menu.

 ![Global Menu]({{< baseurl >}}/img/rancher/global-menu.png)

@@ -116,3 +121,54 @@ Alternatively, you can switch between projects and clusters using the main menu.

 - To switch between clusters, open the **Global** view and select **Clusters** from the main menu. Then open a cluster.
 - To switch between projects, open a cluster, and then select **Projects/Namespaces** from the main menu. Select the link for the project that you want to open.
+
+## Namespaces
+
+Within Rancher, you can further divide projects into different [namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/), which are virtual clusters within a project backed by a physical cluster. Should you require another level of organization beyond projects and the `default` namespace, you can use multiple namespaces to isolate applications and resources.
+
+Although you assign resources at the project level so that each namespace can in the project can use them, you can override this inheritance by assigning resources explicitly to a namespace.
+
+Resources that you can assign directly to namespaces include:
+
+- [Workloads]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/workloads/)
+- [Load Balancers/Ingress]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/load-balancers-and-ingress/)
+- [Service Discovery Records]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/service-discovery/)
+- [Persistent Volume Claims]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/persistent-volume-claims/)
+- [Certificates]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/certificates/)
+- [ConfigMaps]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/configmaps/)
+- [Registries]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/registries/)
+- [Secrets]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/secrets/)
+
+>**Note:** Although you can assign role-based access to namespaces in the base version of Kubernetes, you cannot assign roles to namespaces in Rancher. Instead, assign role-based access at the project level.
+
+### Creating Namespaces
+
+Create a new namespace to isolate apps and resources in a project.
+
+>**Tip:** When working with project resources that you can assign to a namespace (i.e., [workloads]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/workloads/deploy-workloads/), [certificates]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/certificates/), [ConfigMaps]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/configmaps), etc.) you can create a namespace on the fly.
+
+1. From the **Global** view, open the project where you want to create a namespace.
+
+    >**Tip:** As a best practice, we recommend creating namespaces from the project level. However, cluster owners and members can can create them from the cluster level as well. 
+
+1. From the main menu, select **Namespace**. The click **Add Namespace**.
+
+1. Enter a **Name** and then click **Create**.
+
+**Result:** Your namespace is added to the project. You can begin assigning cluster resources to the namespace.
+
+### Moving Namespaces to Another Project
+
+Cluster admins and members may occasionally need to move a namespace to another project, such as when you want a different team to start using the application.
+
+1. From the **Global** view, open the cluster that contains the namespace you want to move.
+
+1. From the main menu, select **Projects/Namespaces**.
+
+1. Select the namespace(s) that you want to move to a different project. Then click **Move**. You can move multiple namespaces at one.
+
+    >**Note:** Don't move the namespaces in the `System` project. Moving these namespaces can adversely affect cluster networking.
+
+1. Choose a new project for the new namespace and then click **Move**. Alternatively, you can remove the namespace from all projects by selecting **None**.
+
+**Result:** Your namespace is moved to a different project (or is unattached from all projects). If any project resources are attached to the namespace, the namespace releases them and then attached resources from the new project. 
@@ -23,7 +23,7 @@ Registries are secrets containing credentials used to authenticate with [private

    >**Note:** Kubernetes classifies secrets, certificates, ConfigMaps, and registries all as [secrets](https://kubernetes.io/docs/concepts/configuration/secret/), and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your registry must have a unique name among all secrets within your workspace.

-1. Select a **Scope** for the registry.
+1. Select a **Scope** for the registry. You can either make the registry available for the entire project or a single [namespace]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#namespaces).

 1. Select the website that hosts your private registry. Then enter credentials that authenticate with the registry.

@@ -22,7 +22,7 @@ When creating a secret, you can make it available for any deployment within a pr

    >**Note:** Kubernetes classifies secrets, certificates, ConfigMaps, and registries all as [secrets](https://kubernetes.io/docs/concepts/configuration/secret/), and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your secret must have a unique name among all secrets within your workspace.

-1. Select a **Scope** for the secret.
+1. Select a **Scope** for the secret. You can either make the registry available for the entire project or a single [namespace]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#namespaces).

 1. From **Secret Values**, click **Add Secret Value** to add a key value pair. Add as many values as you need.

@@ -5,11 +5,10 @@ aliases:
  - /rancher/v2.x/en/tasks/workloads/add-a-dns-record/
 ---

-
 For every workload created, a complementing Service Discovery entry is created. This Service Discovery entry enables DNS resolution for the workload's pods using the following naming convention:
 `<workload>.<namespace>.svc.cluster.local`.

-However, you also have the option of creating additional Service Discovery records. You can use these additional records so that a given namespace resolves with one or more external IP addresses, an external hostname, an alias to another DNS record, other workloads, or a set of pods that match a selector that you create.
+However, you also have the option of creating additional Service Discovery records. You can use these additional records so that a given [namespace]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#namespaces) resolves with one or more external IP addresses, an external hostname, an alias to another DNS record, other workloads, or a set of pods that match a selector that you create.

 1. From the **Global** view, open the project that you want to add a DNS record to.

@@ -50,6 +49,4 @@ However, you also have the option of creating additional Service Discovery recor

 ## Related Links

-### External Links
-
 - [Adding entries to Pod /etc/hosts with HostAliases](https://kubernetes.io/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/)
@@ -5,7 +5,7 @@ aliases:
  - /rancher/v2.x/en/tasks/workloads/add-persistent-volume-claim
 ---

-_Persistent Volume Claims_ (or PVCs) are objects that request storage resources from your cluster. They're similar to a voucher that your deployment can redeem for storage access. When you create a deployment, you should usually attach a PVC so that your application can lay claim to persistent storage. This claim lets your deployment application store its data in an external location, so that if one of the application's containers fails, it can be replaced with a new container and continue accessing its data stored externally, as though an outage never occured.
+_Persistent Volume Claims_ (or PVCs) are objects that request storage resources from your cluster. They're similar to a voucher that your deployment can redeem for storage access. When you create a deployment, you should usually attach a PVC so that your application can lay claim to persistent storage. This claim lets your deployment application store its data in an external location, so that if one of the application's containers fails, it can be replaced with a new container and continue accessing its data stored externally, as though an outage never occurred.

 - Rancher lets you create as many PVCs within a project as you'd like.
 - You can mount PVCs to a deployment as you create it, or later after its running.
@@ -20,7 +20,7 @@ _Persistent Volume Claims_ (or PVCs) are objects that request storage resources

 1. Enter a **Name** for the volume claim.

-1. Select the **Namespace** of the volume claim.
+1. Select the [Namespace]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#namespaces) of the volume claim.

 1. Select a **Source** option:

@@ -17,7 +17,7 @@ Deploy a workload to run an application in one or more containers.

 1. From the **Docker Image** field, enter the name of the Docker image that you want to deploy to the project. During deployment, Rancher pulls this image from [Docker Hub](https://hub.docker.com/explore/). Enter the name exactly as it appears on Docker Hub.

-1. Either select an existing [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/), or click **Add to a new namespace** and enter a new namespace.
+1. Either select an existing [namespace]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#namespaces), or click **Add to a new namespace** and enter a new namespace.

 1. Click **Add Port** to enter a port mapping, which enables access to the application inside and outside of the cluster . For more information, see [Services]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/workloads/#services).