public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-04-14 18:35:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into copilot/update-deprecation-policy-links

Browse Source
This commit is contained in:
Silvio Moioli
2025-12-16 08:57:52 +01:00
committed by GitHub
parent d5155ccdee 033a6ecb52
commit 7aabf39e2c
12 changed files with 157 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/api/workflows/projects.md
View File

@@ -25,11 +25,15 @@ spec:
EOF
```
Use `metadata.generateName` to ensure a unique project ID, but note that `kubectl apply` does not work with `metadata.generateName`, so `kubectl create` must be used instead.
When creating a new project, you have two primary options for setting the name:
- **Automatic Generation:** Use `metadata.generateName` to ensure a unique project ID. However, note that you must use `kubectl create` (instead of `kubectl apply`) with this option, as `kubectl apply` does not support it.
- **Manual Naming:** You can explicitly set the project ID using `metadata.name`. If a project with that exact name already exists, the name request is denied.
The display name seen in the UI is set by `spec.displayName`. If `spec.displayName` is not provided, the field `metadata.name` is used instead.
Set `metadata.namespace` and `spec.clusterName` to the ID for the cluster the project belongs to.
If you create a project through a cluster member account, you must include the annotation, `field.cattle.io/creatorId`, and set it to the cluster member account's user ID.
If you create a project through a cluster member account and want that account to be able to access the project, you must include the annotation `field.cattle.io/creatorId`, and set it to the cluster member account's user ID.
```bash
kubectl create -f - <<EOF
@@ -46,7 +50,7 @@ spec:
EOF
```
Setting the `field.cattle.io/creatorId` field allows the cluster member account to see project resources with the `get` command and view the project in the Rancher UI. Cluster owner and admin accounts don't need to set this annotation to perform these tasks.
Setting the `field.cattle.io/creatorId` field creates a `ProjectRoleTemplateBinding` that grants the specified user the ability to see project resources with the `get` command and view the project in the Rancher UI. Cluster owner and admin accounts don't need to set this annotation to perform these tasks.
Setting the `field.cattle.io/creator-principal-name` annotation to the user's principal preserves it in a projectroletemplatebinding automatically created for the project owner.
@@ -97,9 +101,13 @@ spec:
EOF
```
### Backing Namespace
After creating the project, the field `status.backingNamespace` gets populated. This represents the namespace in the management cluster that is created to manage project related resources. Examples of resources stored in the backing namespace are [project scoped secrets](../../how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) and [project role template bindings](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles).
## Adding a Member to a Project
Look up the project ID to specify the `metadata.namespace` field and `projectName` field values.
Look up the project's [backing namespace](#backing-namespace) to specify the `metadata.namespace` field value and look up the project's ID to specify the `projectName` field value.
```bash
kubectl --namespace c-m-abcde get projects
@@ -119,7 +127,7 @@ apiVersion: management.cattle.io/v3
kind: ProjectRoleTemplateBinding
metadata:
generateName: prtb-
namespace: p-vwxyz
namespace: c-m-abcde-p-vwxyz
projectName: c-m-abcde:p-vwxyz
roleTemplateName: project-member
userPrincipalName: keycloak_user://user
@@ -145,16 +153,16 @@ Create a projectroletemplatebinding for each role you want to assign to the proj
## Listing Project Members
Look up the project ID:
Look up the project backing namespace:
```bash
kubectl --namespace c-m-abcde get projects
```
to list projectroletemplatebindings in the project's namespace:
To list projectroletemplatebindings in the project's backing namespace:
```bash
kubectl --namespace p-vwxyz get projectroletemplatebindings
kubectl --namespace c-m-abcde-p-vwxyz get projectroletemplatebindings
```
## Deleting a Member From a Project
@@ -164,14 +172,14 @@ Lookup the projectroletemplatebinding IDs containing the member in the project's
Delete the projectroletemplatebinding from the project's namespace:
```bash
kubectl --namespace p-vwxyz delete projectroletemplatebindings prtb-qx874 prtb-7zw7s
kubectl --namespace c-m-abcde-p-vwxyz delete projectroletemplatebindings prtb-qx874 prtb-7zw7s
```
## Creating a Namespace in a Project
The Project resource resides in the management cluster, even if the Project is for a managed cluster. The namespaces under the project reside in the managed cluster.
On the management cluster, look up the project ID for the cluster you are administrating since it generated using `metadata.generateName`:
On the management cluster, look up the project ID for the cluster you are administrating if generated using `metadata.generateName`:
```bash
kubectl --namespace c-m-abcde get projects
@@ -207,3 +215,5 @@ kubectl --namespace c-m-abcde delete project p-vwxyz
```
Note that this command doesn't delete the namespaces and resources that formerly belonged to the project.
It does delete all project role template bindings for the projects, so recreating the project will not restore members added to the project, and you have to add users as members again.

6
docs/how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md
View File

@@ -13,7 +13,7 @@ A project is a group of namespaces, and it is a concept introduced by Rancher. P
:::note
Projects are de-emphasized on the UI because it is not required to create Kubernetes resources within a project scope. However, resources such as [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) can still be created in a project scope if the legacy feature flag is enabled.
Projects are de-emphasized on the UI because it is not required to create Kubernetes resources within a project scope. However, resources such as [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) can still be created in a project scope.
:::
@@ -196,3 +196,7 @@ To add a resource quota,
1. Select **Delete**.
When you delete a project, any namespaces that were formerly associated with the project will remain on the cluster. You can find these namespaces in the Rancher UI, in the **Not in a Project** tab of the **Projects/Namespaces** page. You can reassign these namespaces to a project by [moving](../manage-namespaces.md#moving-namespaces-to-another-project) them.
## Further Reading
You can create projects and project members more programmatically via the [Public API](../../../api/quickstart.md). See the [project workflow doc](../../../api/workflows/projects.md) for more information.

30
versioned_docs/version-2.10/api/workflows/projects.md
View File

@@ -25,11 +25,15 @@ spec:
EOF
```
Use `metadata.generateName` to ensure a unique project ID, but note that `kubectl apply` does not work with `metadata.generateName`, so `kubectl create` must be used instead.
When creating a new project, you have two primary options for setting the name:
- **Automatic Generation:** Use `metadata.generateName` to ensure a unique project ID. However, note that you must use `kubectl create` (instead of `kubectl apply`) with this option, as `kubectl apply` does not support it.
- **Manual Naming:** You can explicitly set the project ID using `metadata.name`. If a project with that exact name already exists, the name request is denied.
The display name seen in the UI is set by `spec.displayName`. If `spec.displayName` is not provided, the field `metadata.name` is used instead.
Set `metadata.namespace` and `spec.clusterName` to the ID for the cluster the project belongs to.
If you create a project through a cluster member account, you must include the annotation, `field.cattle.io/creatorId`, and set it to the cluster member account's user ID.
If you create a project through a cluster member account and want that account to be able to access the project, you must include the annotation `field.cattle.io/creatorId`, and set it to the cluster member account's user ID.
```bash
kubectl create -f - <<EOF
@@ -46,7 +50,7 @@ spec:
EOF
```
Setting the `field.cattle.io/creatorId` field allows the cluster member account to see project resources with the `get` command and view the project in the Rancher UI. Cluster owner and admin accounts don't need to set this annotation to perform these tasks.
Setting the `field.cattle.io/creatorId` field creates a `ProjectRoleTemplateBinding` that grants the specified user the ability to see project resources with the `get` command and view the project in the Rancher UI. Cluster owner and admin accounts don't need to set this annotation to perform these tasks.
Setting the `field.cattle.io/creator-principal-name` annotation to the user's principal preserves it in a projectroletemplatebinding automatically created for the project owner.
@@ -97,9 +101,13 @@ spec:
EOF
```
### Backing Namespace
After creating the project, the field `status.backingNamespace` gets populated. This represents the namespace in the management cluster that is created to manage project related resources. Examples of resources stored in the backing namespace are [project scoped secrets](../../how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) and [project role template bindings](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles).
## Adding a Member to a Project
Look up the project ID to specify the `metadata.namespace` field and `projectName` field values.
Look up the project's [backing namespace](#backing-namespace) to specify the `metadata.namespace` field value and look up the project's ID to specify the `projectName` field value.
```bash
kubectl --namespace c-m-abcde get projects
@@ -119,7 +127,7 @@ apiVersion: management.cattle.io/v3
kind: ProjectRoleTemplateBinding
metadata:
generateName: prtb-
namespace: p-vwxyz
namespace: c-m-abcde-p-vwxyz
projectName: c-m-abcde:p-vwxyz
roleTemplateName: project-member
userPrincipalName: keycloak_user://user
@@ -145,16 +153,16 @@ Create a projectroletemplatebinding for each role you want to assign to the proj
## Listing Project Members
Look up the project ID:
Look up the project backing namespace:
```bash
kubectl --namespace c-m-abcde get projects
```
to list projectroletemplatebindings in the project's namespace:
To list projectroletemplatebindings in the project's backing namespace:
```bash
kubectl --namespace p-vwxyz get projectroletemplatebindings
kubectl --namespace c-m-abcde-p-vwxyz get projectroletemplatebindings
```
## Deleting a Member From a Project
@@ -164,14 +172,14 @@ Lookup the projectroletemplatebinding IDs containing the member in the project's
Delete the projectroletemplatebinding from the project's namespace:
```bash
kubectl --namespace p-vwxyz delete projectroletemplatebindings prtb-qx874 prtb-7zw7s
kubectl --namespace c-m-abcde-p-vwxyz delete projectroletemplatebindings prtb-qx874 prtb-7zw7s
```
## Creating a Namespace in a Project
The Project resource resides in the management cluster, even if the Project is for a managed cluster. The namespaces under the project reside in the managed cluster.
On the management cluster, look up the project ID for the cluster you are administrating since it generated using `metadata.generateName`:
On the management cluster, look up the project ID for the cluster you are administrating if generated using `metadata.generateName`:
```bash
kubectl --namespace c-m-abcde get projects
@@ -207,3 +215,5 @@ kubectl --namespace c-m-abcde delete project p-vwxyz
```
Note that this command doesn't delete the namespaces and resources that formerly belonged to the project.
It does delete all project role template bindings for the projects, so recreating the project will not restore members added to the project, and you have to add users as members again.

8
versioned_docs/version-2.10/how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md
View File

@@ -13,7 +13,7 @@ A project is a group of namespaces, and it is a concept introduced by Rancher. P
:::note
Projects are de-emphasized on the UI because it is not required to create Kubernetes resources within a project scope. However, resources such as [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) can still be created in a project scope if the legacy feature flag is enabled.
Projects are de-emphasized on the UI because it is not required to create Kubernetes resources within a project scope. However, resources such as [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) can still be created in a project scope.
:::
@@ -107,7 +107,7 @@ The `system` project:
:::note
In RKE clusters where the project network isolation option is enabled, the `system` project overrides the project network isolation option so that it can communicate with other projects, collect logs, and check health.
In RKE2/K3s clusters where the project network isolation option is enabled, the `system` project overrides the project network isolation option so that it can communicate with other projects, collect logs, and check health.
:::
@@ -196,3 +196,7 @@ To add a resource quota,
1. Select **Delete**.
When you delete a project, any namespaces that were formerly associated with the project will remain on the cluster. You can find these namespaces in the Rancher UI, in the **Not in a Project** tab of the **Projects/Namespaces** page. You can reassign these namespaces to a project by [moving](../manage-namespaces.md#moving-namespaces-to-another-project) them.
## Further Reading
You can create projects and project members more programmatically via the [Public API](../../../api/quickstart.md). See the [project workflow doc](../../../api/workflows/projects.md) for more information.

30
versioned_docs/version-2.11/api/workflows/projects.md
View File

@@ -25,11 +25,15 @@ spec:
EOF
```
Use `metadata.generateName` to ensure a unique project ID, but note that `kubectl apply` does not work with `metadata.generateName`, so `kubectl create` must be used instead.
When creating a new project, you have two primary options for setting the name:
- **Automatic Generation:** Use `metadata.generateName` to ensure a unique project ID. However, note that you must use `kubectl create` (instead of `kubectl apply`) with this option, as `kubectl apply` does not support it.
- **Manual Naming:** You can explicitly set the project ID using `metadata.name`. If a project with that exact name already exists, the name request is denied.
The display name seen in the UI is set by `spec.displayName`. If `spec.displayName` is not provided, the field `metadata.name` is used instead.
Set `metadata.namespace` and `spec.clusterName` to the ID for the cluster the project belongs to.
If you create a project through a cluster member account, you must include the annotation, `field.cattle.io/creatorId`, and set it to the cluster member account's user ID.
If you create a project through a cluster member account and want that account to be able to access the project, you must include the annotation `field.cattle.io/creatorId`, and set it to the cluster member account's user ID.
```bash
kubectl create -f - <<EOF
@@ -46,7 +50,7 @@ spec:
EOF
```
Setting the `field.cattle.io/creatorId` field allows the cluster member account to see project resources with the `get` command and view the project in the Rancher UI. Cluster owner and admin accounts don't need to set this annotation to perform these tasks.
Setting the `field.cattle.io/creatorId` field creates a `ProjectRoleTemplateBinding` that grants the specified user the ability to see project resources with the `get` command and view the project in the Rancher UI. Cluster owner and admin accounts don't need to set this annotation to perform these tasks.
Setting the `field.cattle.io/creator-principal-name` annotation to the user's principal preserves it in a projectroletemplatebinding automatically created for the project owner.
@@ -97,9 +101,13 @@ spec:
EOF
```
### Backing Namespace
After creating the project, the field `status.backingNamespace` gets populated. This represents the namespace in the management cluster that is created to manage project related resources. Examples of resources stored in the backing namespace are [project scoped secrets](../../how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) and [project role template bindings](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles).
## Adding a Member to a Project
Look up the project ID to specify the `metadata.namespace` field and `projectName` field values.
Look up the project's [backing namespace](#backing-namespace) to specify the `metadata.namespace` field value and look up the project's ID to specify the `projectName` field value.
```bash
kubectl --namespace c-m-abcde get projects
@@ -119,7 +127,7 @@ apiVersion: management.cattle.io/v3
kind: ProjectRoleTemplateBinding
metadata:
generateName: prtb-
namespace: p-vwxyz
namespace: c-m-abcde-p-vwxyz
projectName: c-m-abcde:p-vwxyz
roleTemplateName: project-member
userPrincipalName: keycloak_user://user
@@ -145,16 +153,16 @@ Create a projectroletemplatebinding for each role you want to assign to the proj
## Listing Project Members
Look up the project ID:
Look up the project backing namespace:
```bash
kubectl --namespace c-m-abcde get projects
```
to list projectroletemplatebindings in the project's namespace:
To list projectroletemplatebindings in the project's backing namespace:
```bash
kubectl --namespace p-vwxyz get projectroletemplatebindings
kubectl --namespace c-m-abcde-p-vwxyz get projectroletemplatebindings
```
## Deleting a Member From a Project
@@ -164,14 +172,14 @@ Lookup the projectroletemplatebinding IDs containing the member in the project's
Delete the projectroletemplatebinding from the project's namespace:
```bash
kubectl --namespace p-vwxyz delete projectroletemplatebindings prtb-qx874 prtb-7zw7s
kubectl --namespace c-m-abcde-p-vwxyz delete projectroletemplatebindings prtb-qx874 prtb-7zw7s
```
## Creating a Namespace in a Project
The Project resource resides in the management cluster, even if the Project is for a managed cluster. The namespaces under the project reside in the managed cluster.
On the management cluster, look up the project ID for the cluster you are administrating since it generated using `metadata.generateName`:
On the management cluster, look up the project ID for the cluster you are administrating if generated using `metadata.generateName`:
```bash
kubectl --namespace c-m-abcde get projects
@@ -207,3 +215,5 @@ kubectl --namespace c-m-abcde delete project p-vwxyz
```
Note that this command doesn't delete the namespaces and resources that formerly belonged to the project.
It does delete all project role template bindings for the projects, so recreating the project will not restore members added to the project, and you have to add users as members again.

8
versioned_docs/version-2.11/how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md
View File

@@ -13,7 +13,7 @@ A project is a group of namespaces, and it is a concept introduced by Rancher. P
:::note
Projects are de-emphasized on the UI because it is not required to create Kubernetes resources within a project scope. However, resources such as [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) can still be created in a project scope if the legacy feature flag is enabled.
Projects are de-emphasized on the UI because it is not required to create Kubernetes resources within a project scope. However, resources such as [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) can still be created in a project scope.
:::
@@ -107,7 +107,7 @@ The `system` project:
:::note
In RKE clusters where the project network isolation option is enabled, the `system` project overrides the project network isolation option so that it can communicate with other projects, collect logs, and check health.
In RKE2/K3s clusters where the project network isolation option is enabled, the `system` project overrides the project network isolation option so that it can communicate with other projects, collect logs, and check health.
:::
@@ -196,3 +196,7 @@ To add a resource quota,
1. Select **Delete**.
When you delete a project, any namespaces that were formerly associated with the project will remain on the cluster. You can find these namespaces in the Rancher UI, in the **Not in a Project** tab of the **Projects/Namespaces** page. You can reassign these namespaces to a project by [moving](../manage-namespaces.md#moving-namespaces-to-another-project) them.
## Further Reading
You can create projects and project members more programmatically via the [Public API](../../../api/quickstart.md). See the [project workflow doc](../../../api/workflows/projects.md) for more information.

30
versioned_docs/version-2.12/api/workflows/projects.md
View File

@@ -25,11 +25,15 @@ spec:
EOF
```
Use `metadata.generateName` to ensure a unique project ID, but note that `kubectl apply` does not work with `metadata.generateName`, so `kubectl create` must be used instead.
When creating a new project, you have two primary options for setting the name:
- **Automatic Generation:** Use `metadata.generateName` to ensure a unique project ID. However, note that you must use `kubectl create` (instead of `kubectl apply`) with this option, as `kubectl apply` does not support it.
- **Manual Naming:** You can explicitly set the project ID using `metadata.name`. If a project with that exact name already exists, the name request is denied.
The display name seen in the UI is set by `spec.displayName`. If `spec.displayName` is not provided, the field `metadata.name` is used instead.
Set `metadata.namespace` and `spec.clusterName` to the ID for the cluster the project belongs to.
If you create a project through a cluster member account, you must include the annotation, `field.cattle.io/creatorId`, and set it to the cluster member account's user ID.
If you create a project through a cluster member account and want that account to be able to access the project, you must include the annotation `field.cattle.io/creatorId`, and set it to the cluster member account's user ID.
```bash
kubectl create -f - <<EOF
@@ -46,7 +50,7 @@ spec:
EOF
```
Setting the `field.cattle.io/creatorId` field allows the cluster member account to see project resources with the `get` command and view the project in the Rancher UI. Cluster owner and admin accounts don't need to set this annotation to perform these tasks.
Setting the `field.cattle.io/creatorId` field creates a `ProjectRoleTemplateBinding` that grants the specified user the ability to see project resources with the `get` command and view the project in the Rancher UI. Cluster owner and admin accounts don't need to set this annotation to perform these tasks.
Setting the `field.cattle.io/creator-principal-name` annotation to the user's principal preserves it in a projectroletemplatebinding automatically created for the project owner.
@@ -97,9 +101,13 @@ spec:
EOF
```
### Backing Namespace
After creating the project, the field `status.backingNamespace` gets populated. This represents the namespace in the management cluster that is created to manage project related resources. Examples of resources stored in the backing namespace are [project scoped secrets](../../how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) and [project role template bindings](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles).
## Adding a Member to a Project
Look up the project ID to specify the `metadata.namespace` field and `projectName` field values.
Look up the project's [backing namespace](#backing-namespace) to specify the `metadata.namespace` field value and look up the project's ID to specify the `projectName` field value.
```bash
kubectl --namespace c-m-abcde get projects
@@ -119,7 +127,7 @@ apiVersion: management.cattle.io/v3
kind: ProjectRoleTemplateBinding
metadata:
generateName: prtb-
namespace: p-vwxyz
namespace: c-m-abcde-p-vwxyz
projectName: c-m-abcde:p-vwxyz
roleTemplateName: project-member
userPrincipalName: keycloak_user://user
@@ -145,16 +153,16 @@ Create a projectroletemplatebinding for each role you want to assign to the proj
## Listing Project Members
Look up the project ID:
Look up the project backing namespace:
```bash
kubectl --namespace c-m-abcde get projects
```
to list projectroletemplatebindings in the project's namespace:
To list projectroletemplatebindings in the project's backing namespace:
```bash
kubectl --namespace p-vwxyz get projectroletemplatebindings
kubectl --namespace c-m-abcde-p-vwxyz get projectroletemplatebindings
```
## Deleting a Member From a Project
@@ -164,14 +172,14 @@ Lookup the projectroletemplatebinding IDs containing the member in the project's
Delete the projectroletemplatebinding from the project's namespace:
```bash
kubectl --namespace p-vwxyz delete projectroletemplatebindings prtb-qx874 prtb-7zw7s
kubectl --namespace c-m-abcde-p-vwxyz delete projectroletemplatebindings prtb-qx874 prtb-7zw7s
```
## Creating a Namespace in a Project
The Project resource resides in the management cluster, even if the Project is for a managed cluster. The namespaces under the project reside in the managed cluster.
On the management cluster, look up the project ID for the cluster you are administrating since it generated using `metadata.generateName`:
On the management cluster, look up the project ID for the cluster you are administrating if generated using `metadata.generateName`:
```bash
kubectl --namespace c-m-abcde get projects
@@ -207,3 +215,5 @@ kubectl --namespace c-m-abcde delete project p-vwxyz
```
Note that this command doesn't delete the namespaces and resources that formerly belonged to the project.
It does delete all project role template bindings for the projects, so recreating the project will not restore members added to the project, and you have to add users as members again.

6
versioned_docs/version-2.12/how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md
View File

@@ -13,7 +13,7 @@ A project is a group of namespaces, and it is a concept introduced by Rancher. P
:::note
Projects are de-emphasized on the UI because it is not required to create Kubernetes resources within a project scope. However, resources such as [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) can still be created in a project scope if the legacy feature flag is enabled.
Projects are de-emphasized on the UI because it is not required to create Kubernetes resources within a project scope. However, resources such as [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) can still be created in a project scope.
:::
@@ -196,3 +196,7 @@ To add a resource quota,
1. Select **Delete**.
When you delete a project, any namespaces that were formerly associated with the project will remain on the cluster. You can find these namespaces in the Rancher UI, in the **Not in a Project** tab of the **Projects/Namespaces** page. You can reassign these namespaces to a project by [moving](../manage-namespaces.md#moving-namespaces-to-another-project) them.
## Further Reading
You can create projects and project members more programmatically via the [Public API](../../../api/quickstart.md). See the [project workflow doc](../../../api/workflows/projects.md) for more information.

30
versioned_docs/version-2.13/api/workflows/projects.md
View File

@@ -25,11 +25,15 @@ spec:
EOF
```
Use `metadata.generateName` to ensure a unique project ID, but note that `kubectl apply` does not work with `metadata.generateName`, so `kubectl create` must be used instead.
When creating a new project, you have two primary options for setting the name:
- **Automatic Generation:** Use `metadata.generateName` to ensure a unique project ID. However, note that you must use `kubectl create` (instead of `kubectl apply`) with this option, as `kubectl apply` does not support it.
- **Manual Naming:** You can explicitly set the project ID using `metadata.name`. If a project with that exact name already exists, the name request is denied.
The display name seen in the UI is set by `spec.displayName`. If `spec.displayName` is not provided, the field `metadata.name` is used instead.
Set `metadata.namespace` and `spec.clusterName` to the ID for the cluster the project belongs to.
If you create a project through a cluster member account, you must include the annotation, `field.cattle.io/creatorId`, and set it to the cluster member account's user ID.
If you create a project through a cluster member account and want that account to be able to access the project, you must include the annotation `field.cattle.io/creatorId`, and set it to the cluster member account's user ID.
```bash
kubectl create -f - <<EOF
@@ -46,7 +50,7 @@ spec:
EOF
```
Setting the `field.cattle.io/creatorId` field allows the cluster member account to see project resources with the `get` command and view the project in the Rancher UI. Cluster owner and admin accounts don't need to set this annotation to perform these tasks.
Setting the `field.cattle.io/creatorId` field creates a `ProjectRoleTemplateBinding` that grants the specified user the ability to see project resources with the `get` command and view the project in the Rancher UI. Cluster owner and admin accounts don't need to set this annotation to perform these tasks.
Setting the `field.cattle.io/creator-principal-name` annotation to the user's principal preserves it in a projectroletemplatebinding automatically created for the project owner.
@@ -97,9 +101,13 @@ spec:
EOF
```
### Backing Namespace
After creating the project, the field `status.backingNamespace` gets populated. This represents the namespace in the management cluster that is created to manage project related resources. Examples of resources stored in the backing namespace are [project scoped secrets](../../how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) and [project role template bindings](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles).
## Adding a Member to a Project
Look up the project ID to specify the `metadata.namespace` field and `projectName` field values.
Look up the project's [backing namespace](#backing-namespace) to specify the `metadata.namespace` field value and look up the project's ID to specify the `projectName` field value.
```bash
kubectl --namespace c-m-abcde get projects
@@ -119,7 +127,7 @@ apiVersion: management.cattle.io/v3
kind: ProjectRoleTemplateBinding
metadata:
generateName: prtb-
namespace: p-vwxyz
namespace: c-m-abcde-p-vwxyz
projectName: c-m-abcde:p-vwxyz
roleTemplateName: project-member
userPrincipalName: keycloak_user://user
@@ -145,16 +153,16 @@ Create a projectroletemplatebinding for each role you want to assign to the proj
## Listing Project Members
Look up the project ID:
Look up the project backing namespace:
```bash
kubectl --namespace c-m-abcde get projects
```
to list projectroletemplatebindings in the project's namespace:
To list projectroletemplatebindings in the project's backing namespace:
```bash
kubectl --namespace p-vwxyz get projectroletemplatebindings
kubectl --namespace c-m-abcde-p-vwxyz get projectroletemplatebindings
```
## Deleting a Member From a Project
@@ -164,14 +172,14 @@ Lookup the projectroletemplatebinding IDs containing the member in the project's
Delete the projectroletemplatebinding from the project's namespace:
```bash
kubectl --namespace p-vwxyz delete projectroletemplatebindings prtb-qx874 prtb-7zw7s
kubectl --namespace c-m-abcde-p-vwxyz delete projectroletemplatebindings prtb-qx874 prtb-7zw7s
```
## Creating a Namespace in a Project
The Project resource resides in the management cluster, even if the Project is for a managed cluster. The namespaces under the project reside in the managed cluster.
On the management cluster, look up the project ID for the cluster you are administrating since it generated using `metadata.generateName`:
On the management cluster, look up the project ID for the cluster you are administrating if generated using `metadata.generateName`:
```bash
kubectl --namespace c-m-abcde get projects
@@ -207,3 +215,5 @@ kubectl --namespace c-m-abcde delete project p-vwxyz
```
Note that this command doesn't delete the namespaces and resources that formerly belonged to the project.
It does delete all project role template bindings for the projects, so recreating the project will not restore members added to the project, and you have to add users as members again.

6
versioned_docs/version-2.13/how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md
View File

@@ -13,7 +13,7 @@ A project is a group of namespaces, and it is a concept introduced by Rancher. P
:::note
Projects are de-emphasized on the UI because it is not required to create Kubernetes resources within a project scope. However, resources such as [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) can still be created in a project scope if the legacy feature flag is enabled.
Projects are de-emphasized on the UI because it is not required to create Kubernetes resources within a project scope. However, resources such as [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) can still be created in a project scope.
:::
@@ -196,3 +196,7 @@ To add a resource quota,
1. Select **Delete**.
When you delete a project, any namespaces that were formerly associated with the project will remain on the cluster. You can find these namespaces in the Rancher UI, in the **Not in a Project** tab of the **Projects/Namespaces** page. You can reassign these namespaces to a project by [moving](../manage-namespaces.md#moving-namespaces-to-another-project) them.
## Further Reading
You can create projects and project members more programmatically via the [Public API](../../../api/quickstart.md). See the [project workflow doc](../../../api/workflows/projects.md) for more information.

34
versioned_docs/version-2.9/api/workflows/projects.md
View File

@@ -25,11 +25,15 @@ spec:
EOF
```
Use `metadata.generateName` to ensure a unique project ID, but note that `kubectl apply` does not work with `metadata.generateName`, so `kubectl create` must be used instead.
When creating a new project, you have two primary options for setting the name:
- **Automatic Generation:** Use `metadata.generateName` to ensure a unique project ID. However, note that you must use `kubectl create` (instead of `kubectl apply`) with this option, as `kubectl apply` does not support it.
- **Manual Naming:** You can explicitly set the project ID using `metadata.name`. If a project with that exact name already exists, the name request is denied.
The display name seen in the UI is set by `spec.displayName`. If `spec.displayName` is not provided, the field `metadata.name` is used instead.
Set `metadata.namespace` and `spec.clusterName` to the ID for the cluster the project belongs to.
If you create a project through a cluster member account, you must include the annotation, `field.cattle.io/creatorId`, and set it to the cluster member account's user ID.
If you create a project through a cluster member account and want that account to be able to access the project, you must include the annotation `field.cattle.io/creatorId`, and set it to the cluster member account's user ID.
```bash
kubectl create -f - <<EOF
@@ -46,7 +50,11 @@ spec:
EOF
```
Setting the `field.cattle.io/creatorId` field allows the cluster member account to see project resources with the `get` command and view the project in the Rancher UI. Cluster owner and admin accounts don't need to set this annotation to perform these tasks.
Setting the `field.cattle.io/creatorId` field creates a `ProjectRoleTemplateBinding` that grants the specified user the ability to see project resources with the `get` command and view the project in the Rancher UI. Cluster owner and admin accounts don't need to set this annotation to perform these tasks.
Setting the `field.cattle.io/creator-principal-name` annotation to the user's principal preserves it in a projectroletemplatebinding automatically created for the project owner.
If you don't want the creator to be added as the owner member (e.g. if the creator is a cluster administrator) to the project you may set the `field.cattle.io/no-creator-rbac` annotation to `true`, which will prevent the corresponding projectroletemplatebinding from being created.
### Creating a Project With a Resource Quota
@@ -93,9 +101,13 @@ spec:
EOF
```
### Backing Namespace
After creating the project, the field `status.backingNamespace` gets populated. This represents the namespace in the management cluster that is created to manage project related resources. Examples of resources stored in the backing namespace are [project scoped secrets](../../how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) and [project role template bindings](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles).
## Adding a Member to a Project
Look up the project ID to specify the `metadata.namespace` field and `projectName` field values.
Look up the project's [backing namespace](#backing-namespace) to specify the `metadata.namespace` field value and look up the project's ID to specify the `projectName` field value.
```bash
kubectl --namespace c-m-abcde get projects
@@ -115,7 +127,7 @@ apiVersion: management.cattle.io/v3
kind: ProjectRoleTemplateBinding
metadata:
generateName: prtb-
namespace: p-vwxyz
namespace: c-m-abcde-p-vwxyz
projectName: c-m-abcde:p-vwxyz
roleTemplateName: project-member
userPrincipalName: keycloak_user://user
@@ -141,16 +153,16 @@ Create a projectroletemplatebinding for each role you want to assign to the proj
## Listing Project Members
Look up the project ID:
Look up the project backing namespace:
```bash
kubectl --namespace c-m-abcde get projects
```
to list projectroletemplatebindings in the project's namespace:
To list projectroletemplatebindings in the project's backing namespace:
```bash
kubectl --namespace p-vwxyz get projectroletemplatebindings
kubectl --namespace c-m-abcde-p-vwxyz get projectroletemplatebindings
```
## Deleting a Member From a Project
@@ -160,14 +172,14 @@ Lookup the projectroletemplatebinding IDs containing the member in the project's
Delete the projectroletemplatebinding from the project's namespace:
```bash
kubectl --namespace p-vwxyz delete projectroletemplatebindings prtb-qx874 prtb-7zw7s
kubectl --namespace c-m-abcde-p-vwxyz delete projectroletemplatebindings prtb-qx874 prtb-7zw7s
```
## Creating a Namespace in a Project
The Project resource resides in the management cluster, even if the Project is for a managed cluster. The namespaces under the project reside in the managed cluster.
On the management cluster, look up the project ID for the cluster you are administrating since it generated using `metadata.generateName`:
On the management cluster, look up the project ID for the cluster you are administrating if generated using `metadata.generateName`:
```bash
kubectl --namespace c-m-abcde get projects
@@ -203,3 +215,5 @@ kubectl --namespace c-m-abcde delete project p-vwxyz
```
Note that this command doesn't delete the namespaces and resources that formerly belonged to the project.
It does delete all project role template bindings for the projects, so recreating the project will not restore members added to the project, and you have to add users as members again.

8
versioned_docs/version-2.9/how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md
View File

@@ -13,7 +13,7 @@ A project is a group of namespaces, and it is a concept introduced by Rancher. P
:::note
Projects are de-emphasized on the UI because it is not required to create Kubernetes resources within a project scope. However, resources such as [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) can still be created in a project scope if the legacy feature flag is enabled.
Projects are de-emphasized on the UI because it is not required to create Kubernetes resources within a project scope. However, resources such as [Secrets](../../new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) can still be created in a project scope.
:::
@@ -107,7 +107,7 @@ The `system` project:
:::note
In RKE clusters where the project network isolation option is enabled, the `system` project overrides the project network isolation option so that it can communicate with other projects, collect logs, and check health.
In RKE2/K3s clusters where the project network isolation option is enabled, the `system` project overrides the project network isolation option so that it can communicate with other projects, collect logs, and check health.
:::
@@ -196,3 +196,7 @@ To add a resource quota,
1. Select **Delete**.
When you delete a project, any namespaces that were formerly associated with the project will remain on the cluster. You can find these namespaces in the Rancher UI, in the **Not in a Project** tab of the **Projects/Namespaces** page. You can reassign these namespaces to a project by [moving](../manage-namespaces.md#moving-namespaces-to-another-project) them.
## Further Reading
You can create projects and project members more programmatically via the [Public API](../../../api/quickstart.md). See the [project workflow doc](../../../api/workflows/projects.md) for more information.