Add graph about workload namespace configuration
- Add a graph about workload namespace configuration. - This change also divides the structure of the namespaces explanation page into "workload namespaces" and "fleet namespaces" for better readability and more clarity. By doing that, another layer of headers is introduced, for which the TOC on the right hand side has been adapted to show the same details as before. - The source of the added graph is added in the `src/img` folder as Mermaid code. - Also, paragraphs have been wrapped to a certain max width.
This commit is contained in:
Patrick Seidensal
parent
b82c54f855
commit
afb8ff989a
|
|
@ -1,81 +1,45 @@
|
|||
---
|
||||
toc_max_heading_level: 4
|
||||
---
|
||||
|
||||
# Namespaces
|
||||
|
||||
All types in the Fleet manager are namespaced. The namespaces of the manager types do not correspond to the namespaces
|
||||
of the deployed resources in the downstream cluster. Understanding how namespaces are used in the Fleet manager is
|
||||
important to understand the security model and how one can use Fleet in a multi-tenant fashion.
|
||||
## Workload Namespaces
|
||||
|
||||
## GitRepos, Bundles, Clusters, ClusterGroups
|
||||
### Namespace Creation Behavior in Bundles
|
||||
|
||||
The primary types are all scoped to a namespace. All selectors for `GitRepo` targets will be evaluated against
|
||||
the `Clusters` and `ClusterGroups` in the same namespaces. This means that if you give `create` or `update` privileges
|
||||
to a `GitRepo` type in a namespace, that end user can modify the selector to match any cluster in that namespace.
|
||||
This means in practice if you want to have two teams self manage their own `GitRepo` registrations but they should
|
||||
not be able to target each others clusters, they should be in different namespaces.
|
||||
When deploying a Fleet bundle, the specified namespace will automatically be
|
||||
created if it does not already exist.
|
||||
|
||||
### GitRepo Namespace
|
||||
### Configuring Workload Namespaces
|
||||
|
||||
Git repos are added to the Fleet manager using the `GitRepo` custom resource type. The `GitRepo` type is namespaced. By default, Rancher will create two Fleet workspaces: **fleet-default** and **fleet-local**.
|
||||
When configuring workload namespaces, it is important to be aware that certain
|
||||
options are designed to override the values of other options or namespace
|
||||
definitions in workload resources. In some cases, setting namespaces using some
|
||||
options may result in errors if the resources to be deployed contain
|
||||
non-namespaced resources. To get a better understanding of how these options
|
||||
interact, refer to the diagram below. For more details on a specific option,
|
||||
please refer to the [GitRepo](./ref-gitrepo.md) or
|
||||
[fleet.yaml](./ref-fleet-yaml.md) reference.
|
||||
|
||||
- `fleet-default` will contain all the downstream clusters that are already registered through Rancher.
|
||||
- `fleet-local` will contain the local cluster by default.
|
||||
|
||||
|
||||
If you are using Fleet in a [single cluster](./concepts.md) style, the namespace will always be **fleet-local**. Check [here](https://fleet.rancher.io/namespaces/#fleet-local) for more on the `fleet-local` namespace.
|
||||
### Cross Namespace Deployments
|
||||
|
||||
For a [multi-cluster](./concepts.md) style, please ensure you use the correct repo that will map to the right target clusters.
|
||||
It is possible to create a GitRepo that will deploy across namespaces. The
|
||||
primary purpose of this is so that a central privileged team can manage common
|
||||
configuration for many clusters that are managed by different teams. The way
|
||||
this is accomplished is by creating a `BundleNamespaceMapping` resource in a
|
||||
cluster.
|
||||
|
||||
If you are creating a `BundleNamespaceMapping` resource it is best to do it in a
|
||||
namespace that only contains `GitRepos` and no `Clusters`. It seems to get
|
||||
confusing if you have Clusters in the same repo as the cross namespace
|
||||
`GitRepos` will still always be evaluated against the current namespace. So if
|
||||
you have clusters in the same namespace you may wish to make them canary
|
||||
clusters.
|
||||
|
||||
## Namespace Creation Behavior in Bundles
|
||||
|
||||
When deploying a Fleet bundle, the specified namespace will automatically be created if it does not already exist.
|
||||
|
||||
## Special Namespaces
|
||||
|
||||
An overview of the [namespaces](./namespaces.md) used by fleet and their resources.
|
||||
|
||||
|
||||
|
||||
### fleet-local (local workspace, cluster registration namespace)
|
||||
|
||||
The **fleet-local** namespace is a special namespace used for the single cluster use case or to bootstrap
|
||||
the configuration of the Fleet manager.
|
||||
|
||||
When fleet is installed the `fleet-local` namespace is created along with one `Cluster` called `local` and one
|
||||
`ClusterGroup` called `default`. If no targets are specified on a `GitRepo`, it is by default targeted to the
|
||||
`ClusterGroup` named `default`. This means that all `GitRepos` created in `fleet-local` will
|
||||
automatically target the `local` `Cluster`. The `local` `Cluster` refers to the cluster the Fleet manager is running
|
||||
on.
|
||||
|
||||
The cluster registration namespace contains the cluster and the clusterregistration resources, as well as any gitrepos and bundles.
|
||||
|
||||
### cattle-fleet-system (system namespace)
|
||||
|
||||
The Fleet controller and Fleet agent run in this namespace. All service accounts referenced by `GitRepos` are expected
|
||||
to live in this namespace in the downstream cluster.
|
||||
|
||||
### cattle-fleet-clusters-system (system registration namespace)
|
||||
|
||||
This namespace holds secrets for the cluster registration process. It should contain no other resources in it,
|
||||
especially secrets.
|
||||
|
||||
### Cluster Namespaces
|
||||
|
||||
For every cluster that is registered a namespace is created by the Fleet manager for that cluster.
|
||||
These namespaces are named in the form `cluster-${namespace}-${cluster}-${random}`. The purpose of this
|
||||
namespace is that all `BundleDeployments` for that cluster are put into this namespace and
|
||||
then the downstream cluster is given access to watch and update `BundleDeployments` in that namespace only.
|
||||
|
||||
## Cross Namespace Deployments
|
||||
|
||||
It is possible to create a GitRepo that will deploy across namespaces. The primary purpose of this is so that a
|
||||
central privileged team can manage common configuration for many clusters that are managed by different teams. The way
|
||||
this is accomplished is by creating a `BundleNamespaceMapping` resource in a cluster.
|
||||
|
||||
If you are creating a `BundleNamespaceMapping` resource it is best to do it in a namespace that only contains `GitRepos`
|
||||
and no `Clusters`. It seems to get confusing if you have Clusters in the same repo as the cross namespace `GitRepos` will still
|
||||
always be evaluated against the current namespace. So if you have clusters in the same namespace you may wish to make them
|
||||
canary clusters.
|
||||
|
||||
A `BundleNamespaceMapping` has only two fields. Which are as below
|
||||
A `BundleNamespaceMapping` has only two fields. Which are as below
|
||||
|
||||
```yaml
|
||||
kind: BundleNamespaceMapping
|
||||
|
|
@ -88,26 +52,29 @@ metadata:
|
|||
# labels field or from the GitRepo metadata.labels field
|
||||
bundleSelector:
|
||||
matchLabels:
|
||||
foo: bar
|
||||
foo: bar
|
||||
|
||||
# Namespaces to match by label
|
||||
namespaceSelector:
|
||||
matchLabels:
|
||||
foo: bar
|
||||
foo: bar
|
||||
```
|
||||
|
||||
If the `BundleNamespaceMappings` `bundleSelector` field matches a `Bundles` labels then that `Bundle` target criteria will
|
||||
be evaluated against all clusters in all namespaces that match `namespaceSelector`. One can specify labels for the created
|
||||
bundles from git by putting labels in the `fleet.yaml` file or on the `metadata.labels` field on the `GitRepo`.
|
||||
If the `BundleNamespaceMappings` `bundleSelector` field matches a `Bundles`
|
||||
labels then that `Bundle` target criteria will be evaluated against all clusters
|
||||
in all namespaces that match `namespaceSelector`. One can specify labels for the
|
||||
created bundles from git by putting labels in the `fleet.yaml` file or on the
|
||||
`metadata.labels` field on the `GitRepo`.
|
||||
|
||||
## Restricting GitRepos
|
||||
### Restricting GitRepos
|
||||
|
||||
A namespace can contain multiple `GitRepoRestriction` resources. All `GitRepos`
|
||||
created in that namespace will be checked against the list of restrictions.
|
||||
If a `GitRepo` violates one of the constraints its `BundleDeployment` will be
|
||||
in an error state and won't be deployed.
|
||||
created in that namespace will be checked against the list of restrictions. If a
|
||||
`GitRepo` violates one of the constraints its `BundleDeployment` will be in an
|
||||
error state and won't be deployed.
|
||||
|
||||
This can also be used to set the defaults for GitRepo's `serviceAccount` and `clientSecretName` fields.
|
||||
This can also be used to set the defaults for GitRepo's `serviceAccount` and
|
||||
`clientSecretName` fields.
|
||||
|
||||
```yaml
|
||||
kind: GitRepoRestriction
|
||||
|
|
@ -123,9 +90,87 @@ defaultClientSecretName: ""
|
|||
defaultServiceAccount: ""
|
||||
```
|
||||
|
||||
### Allowed Target Namespaces
|
||||
#### Allowed Target Namespaces
|
||||
|
||||
This can be used to limit a deployment to a set of namespaces on a downstream
|
||||
cluster. If an allowedTargetNamespaces restriction is present, all `GitRepos`
|
||||
cluster. If an allowedTargetNamespaces restriction is present, all `GitRepos`
|
||||
must specify a `targetNamespace` and the specified namespace must be in the
|
||||
allow list. This also prevents the creation of cluster wide resources.
|
||||
allow list. This also prevents the creation of cluster wide resources.
|
||||
|
||||
## Fleet Namespaces
|
||||
|
||||
All types in the Fleet manager are namespaced. The namespaces of the manager
|
||||
types do not correspond to the namespaces of the deployed resources in the
|
||||
downstream cluster. Understanding how namespaces are used in the Fleet manager
|
||||
is important to understand the security model and how one can use Fleet in a
|
||||
multi-tenant fashion.
|
||||
|
||||
### GitRepos, Bundles, Clusters, ClusterGroups
|
||||
|
||||
The primary types are all scoped to a namespace. All selectors for `GitRepo`
|
||||
targets will be evaluated against the `Clusters` and `ClusterGroups` in the same
|
||||
namespaces. This means that if you give `create` or `update` privileges to a
|
||||
`GitRepo` type in a namespace, that end user can modify the selector to match
|
||||
any cluster in that namespace. This means in practice if you want to have two
|
||||
teams self manage their own `GitRepo` registrations but they should not be able
|
||||
to target each others clusters, they should be in different namespaces.
|
||||
|
||||
#### GitRepo Namespace
|
||||
|
||||
Git repos are added to the Fleet manager using the `GitRepo` custom resource
|
||||
type. The `GitRepo` type is namespaced. By default, Rancher will create two
|
||||
Fleet workspaces: **fleet-default** and **fleet-local**.
|
||||
|
||||
- `fleet-default` will contain all the downstream clusters that are already
|
||||
registered through Rancher.
|
||||
- `fleet-local` will contain the local cluster by default.
|
||||
|
||||
If you are using Fleet in a [single cluster](./concepts.md) style, the namespace
|
||||
will always be **fleet-local**. Check
|
||||
[here](https://fleet.rancher.io/namespaces/#fleet-local) for more on the
|
||||
`fleet-local` namespace.
|
||||
|
||||
For a [multi-cluster](./concepts.md) style, please ensure you use the correct
|
||||
repo that will map to the right target clusters.
|
||||
|
||||
### Special Namespaces
|
||||
|
||||
An overview of the [namespaces](./namespaces.md) used by fleet and their
|
||||
resources.
|
||||
|
||||
|
||||
|
||||
#### fleet-local (local workspace, cluster registration namespace)
|
||||
|
||||
The **fleet-local** namespace is a special namespace used for the single cluster
|
||||
use case or to bootstrap the configuration of the Fleet manager.
|
||||
|
||||
When fleet is installed the `fleet-local` namespace is created along with one
|
||||
`Cluster` called `local` and one `ClusterGroup` called `default`. If no targets
|
||||
are specified on a `GitRepo`, it is by default targeted to the `ClusterGroup`
|
||||
named `default`. This means that all `GitRepos` created in `fleet-local` will
|
||||
automatically target the `local` `Cluster`. The `local` `Cluster` refers to the
|
||||
cluster the Fleet manager is running on.
|
||||
|
||||
The cluster registration namespace contains the cluster and the
|
||||
clusterregistration resources, as well as any gitrepos and bundles.
|
||||
|
||||
#### cattle-fleet-system (system namespace)
|
||||
|
||||
The Fleet controller and Fleet agent run in this namespace. All service accounts
|
||||
referenced by `GitRepos` are expected to live in this namespace in the
|
||||
downstream cluster.
|
||||
|
||||
#### cattle-fleet-clusters-system (system registration namespace)
|
||||
|
||||
This namespace holds secrets for the cluster registration process. It should
|
||||
contain no other resources in it, especially secrets.
|
||||
|
||||
#### Cluster Namespaces
|
||||
|
||||
For every cluster that is registered a namespace is created by the Fleet manager
|
||||
for that cluster. These namespaces are named in the form
|
||||
`cluster-${namespace}-${cluster}-${random}`. The purpose of this namespace is
|
||||
that all `BundleDeployments` for that cluster are put into this namespace and
|
||||
then the downstream cluster is given access to watch and update
|
||||
`BundleDeployments` in that namespace only.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,31 @@
|
|||
graph TD
|
||||
start([Start]) --> gitRepoNS
|
||||
|
||||
failsForClusterScopedResources("`Fails if a cluster scoped resource is used in the workload manifests.`")
|
||||
style failsForClusterScopedResources stroke:#f66,stroke-dasharray: 5, 5
|
||||
|
||||
gitRepoNS["`In any **GitRepo** resource, field **targetNamespace**
|
||||
|
||||
Overrides everything.`"]
|
||||
|
||||
|
||||
fleetYamlNS["`In file **fleet.yaml**, field **namespace**
|
||||
|
||||
Overrides namespaces defined in workload manifests.`"]
|
||||
|
||||
workloadNS["`In **any workload's manifest**, field **metadata.namespace**`"]
|
||||
|
||||
fleetYamlDefaultNS["`In file **fleet.yaml**, field **defaultNamespace**
|
||||
|
||||
This is what manifests get if they don't have a namespace defined.`"]
|
||||
|
||||
failsForClusterScopedResources .-> gitRepoNS
|
||||
failsForClusterScopedResources .-> fleetYamlNS
|
||||
|
||||
gitRepoNS -->|if not exist| fleetYamlNS
|
||||
fleetYamlNS -->|if not exist| workloadNS
|
||||
workloadNS -->|if not exist| fleetYamlDefaultNS
|
||||
|
||||
ende(["`Errors out if no namespace was defined up to this point.`"])
|
||||
|
||||
fleetYamlDefaultNS -->|if not exist| ende
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 74 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 14 KiB |
Loading…
Reference in New Issue