diff --git a/docs/gitrepo-add.md b/docs/gitrepo-add.md index c545f54af..d3f9d7d1e 100644 --- a/docs/gitrepo-add.md +++ b/docs/gitrepo-add.md @@ -161,7 +161,7 @@ Example: path-one: # path path-one must exist in the repository username: user password: pass -path-two: # path path-one must exist in the repository +path-two: # path path-one must exist in the repository username: user2 password: pass2 caBundle: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCiAgICBNSUlEblRDQ0FvV2dBd0lCQWdJVUNwMHB2SVJTb2c0eHJKN2Q1SUI2ME1ka0k1WXdEUVlKS29aSWh2Y05BUUVMCiAgICBCUUF3WGpFTE1Ba0dBMVVFQmhNQ1FWVXhFekFSQmdOVkJBZ01DbE52YldVdFUzUmhkR1V4SVRBZkJnTlZCQW9NCiAgICBHRWx1ZEdWeWJtVjBJRmRwWkdkcGRITWdVSFI1SUV4MFpERVhNQlVHQTFVRUF3d09jbUZ1WTJobGNpNXRlUzV2CiAgICBjbWN3SGhjTk1qTXdOREkzTVRVd056VXpXaGNOTWpnd05ESTFNVFV3TnpVeldqQmVNUXN3Q1FZRFZRUUdFd0pCCiAgICBWVEVUTUJFR0ExVUVDQXdLVTI5dFpTMVRkR0YwWlRFaE1COEdBMVVFQ2d3WVNXNTBaWEp1WlhRZ1YybGtaMmwwCiAgICBjeUJRZEhrZ1RIUmtNUmN3RlFZRFZRUUREQTV5WVc1amFHVnlMbTE1TG05eVp6Q0NBU0l3RFFZSktvWklodmNOCiAgICBBUUVCQlFBRGdnRVBBRENDQVFvQ2dnRUJBTXBvZE5TMDB6NDc1dnVSc2ZZcTFRYTFHQVl3QU92anV4MERKTHY5CiAgICBrZFhwT091dGdjMU8yWUdqNUlCVGQzVmpISmFJYUg3SDR2Rm84RlBaMG9zcU9YaFg3eUM4STdBS3ZhOEE5VmVmCiAgICBJVXp6Vlo1cCs1elNxRjdtZTlOaUNiL0pVSkZLT0ZsTkF4cjZCcXhoMEIyN1VZTlpjaUIvL1V0L0I2eHJuVE55CiAgICBoRzJiNzk4bjg4bFZqY3EzbEE0djFyM3VzWGYxVG5aS2t2UEN4ZnFHYk5OdTlpTjdFZnZHOWoyekdHcWJvcDRYCiAgICBXY3VSa3N3QkgxZlRNS0ZrbGcrR1VsZkZPMGFzL3phalVOdmdweTlpdVBMZUtqZTVWcDBiMlBLd09qUENpV2d4CiAgICBabDJlVDlNRnJjV0F3NTg3emE5NDBlT1Era2pkdmVvUE5sU2k3eVJMMW96YlRka0NBd0VBQWFOVE1GRXdIUVlECiAgICBWUjBPQkJZRUZEQkNkYjE4M1hsU0tWYzBxNmJSTCt0dVNTV3lNQjhHQTFVZEl3UVlNQmFBRkRCQ2RiMTgzWGxTCiAgICBLVmMwcTZiUkwrdHVTU1d5TUE4R0ExVWRFd0VCL3dRRk1BTUJBZjh3RFFZSktvWklodmNOQVFFTEJRQURnZ0VCCiAgICBBQ1BCVERkZ0dCVDVDRVoxd1pnQmhKdm9GZTk2MUJqVCtMU2RxSlpsSmNRZnlnS0hyNks5ZmZaY1ZlWlBoMVU0CiAgICB3czBuWGNOZiszZGJlTjl4dVBiY0VqUWlQaFJCcnRzalE1T1JiVHdYWEdBdzlYbDZYTkl6YjN4ZDF6RWFzQXZPCiAgICBJMjM2ZHZXQ1A0dWoycWZqR0FkQjJnaXU2b2xHK01CWHlneUZKMElzRENraldLZysyWEdmU3lyci9KZU1vZlFBCiAgICB1VU9wcFVGdERYd0lrUW1VTGNVVUxWcTdtUVNQb0lzVkNNM2hKNVQzczdUSWtHUDZVcGVSSjgzdU9LbURYMkRHCiAgICBwVWVQVHBuVWVLOVMzUEVKTi9XcmJSSVd3WU1OR29qdDRKWitaK1N6VE1aVkh0SlBzaGpjL1hYOWZNU1ZXQmlzCiAgICBQRW5MU256MDQ4OGFUQm5SUFlnVXFsdz0KICAgIC0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0= @@ -169,6 +169,7 @@ path-two: # path path-one must exist in the repository ``` Create the secret + ``` kubectl create secret generic path-auth-secret -n fleet-default --from-file=secrets-path.yaml ``` @@ -178,11 +179,9 @@ In the previous example credentials for username `user` will be used for the pat `caBundle` and `sshPrivateKey` must be base64 encoded. - :::note If you are using ["rancher-backups"](https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher) and want this secret to be included the backup, please add the label `resources.cattle.io/backup: true` to the secret. In that case, make sure to encrypt the backup to protect sensitive credentials. - # Troubleshooting See Fleet Troubleshooting section [here](./troubleshooting.md). diff --git a/docs/namespaces.md b/docs/namespaces.md index 77f7f96f3..97c16f71f 100644 --- a/docs/namespaces.md +++ b/docs/namespaces.md @@ -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. +![Configuring Workload Namespaces](/img/FleetWorkloadNamespaces.png) -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. - -![Namespace](/img/FleetNamespaces.svg) - -### 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,10 +90,84 @@ 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` must -specify a `targetNamespace` and the specified namespace must be in the allow -list. -This also prevents the creation of cluster wide resources. +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` +must specify a `targetNamespace` and the specified namespace must be in the +allow list. This also prevents the creation of cluster wide resources. + +## Fleet Namespaces + +All types in the Fleet manager are namespaced. The namespaces of a custom +resource, e.g. GitRepo, does not influence the namespace of deployed resources. + +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. + +![Namespace](/img/FleetNamespaces.svg) + +### GitRepos, Bundles, Clusters, ClusterGroups + +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. + +The cluster registration namespace, called 'workspace' in Rancher, contains the `Cluster` and the +`ClusterRegistration` resources, as well as any `GitRepos` and `Bundles`. + +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. Access to + `fleet-local` is limited. + +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. + +### Internal Namespaces + +#### Cluster Registration Namespace: fleet-local + +The **fleet-local** namespace is a special namespace used for the single cluster +use case or to bootstrap the configuration of the Fleet manager. +Access to the local cluster should be limited to operators. + +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. + +#### System Namespace: cattle-fleet-system + +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. + +#### System Registration Namespace: cattle-fleet-clusters-system + +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. diff --git a/src/img/FleetWorkloadNamespaces.mmd b/src/img/FleetWorkloadNamespaces.mmd new file mode 100644 index 000000000..e0c4921c9 --- /dev/null +++ b/src/img/FleetWorkloadNamespaces.mmd @@ -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 diff --git a/static/img/FleetWorkloadNamespaces.png b/static/img/FleetWorkloadNamespaces.png new file mode 100644 index 000000000..86b6735aa Binary files /dev/null and b/static/img/FleetWorkloadNamespaces.png differ diff --git a/static/img/FleetWorkloadNamespaces.svg b/static/img/FleetWorkloadNamespaces.svg new file mode 100644 index 000000000..72af6f3ad --- /dev/null +++ b/static/img/FleetWorkloadNamespaces.svg @@ -0,0 +1,7 @@ +
if not exist
if not exist
if not exist
if not exist
Start
+

In any GitRepo resource, field targetNamespace

Overrides everything.

+

Fails if a cluster scoped resource is used in the workload manifests.

+

In file fleet.yaml, field namespace

Overrides namespaces defined in workload manifests.

+

In any workload's manifest, field metadata.namespace

+

In file fleet.yaml, field defaultNamespace

This is what manifests get if they don't have a namespace defined.

+

Errors out if no namespace was defined up to this point.

 \ No newline at end of file