rancher
/
fleet-docs
mirror of https://github.com/rancher/fleet-docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Single page for cluster registration

This commit is contained in:
Mario Manno 2023-03-02 14:56:19 +01:00
parent 45cc06361e
commit f53c0f1dbb
12 changed files with 112 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/architecture.md
View File

@ -18,7 +18,7 @@ goes from the managed cluster to the Fleet manager. The fleet manager does not i
connections to downstream clusters. This means managed clusters can run in private networks and behind
NATs. The only requirement is the cluster agent needs to be able to communicate with the
Kubernetes API of the cluster running the Fleet manager. The one exception to this is if you use
the [manager initiated](./manager-initiated.md) cluster registration flow. This is not required, but
the [manager initiated](./cluster-registration.md#manager-initiated) cluster registration flow. This is not required, but
an optional pattern.
The cluster agents are not assumed to have an "always on" connection. They will resume operation as

2
docs/cluster-group.md
View File

@ -1,4 +1,4 @@
# Cluster Groups
# Create Cluster Groups
Clusters in a namespace can be put into a cluster group. A cluster group is essentially a named selector.
The only parameter for a cluster group is essentially the selector.

25
docs/cluster-overview.md
View File

@ -1,25 +0,0 @@
# Overview
There are two specific styles to registering clusters. These styles will be referred
to as **agent initiated** and **manager initiated** registration. Typically one would
go with the agent initiated registration but there are specific use cases in which
manager initiated is a better workflow.
## Agent Initiated Registration
Agent initiated refers to a pattern in which the downstream cluster installs an agent with a
[cluster registration token](./cluster-tokens.md) and optionally a client ID. The cluster
agent will then make a API request to the Fleet manager and initiate the registration process. Using
this process the Manager will never make an outbound API request to the downstream clusters and will thus
never need to have direct network access. The downstream cluster only needs to make outbound HTTPS
calls to the manager.
## Manager Initiated Registration
Manager initiated registration is a process in which you register an existing Kubernetes cluster
with the Fleet manager and the Fleet manager will make an API call to the downstream cluster to
deploy the agent. This style can place additional network access requirements because the Fleet
manager must be able to communicate with the downstream cluster API server for the registration process.
After the cluster is registered there is no further need for the manager to contact the downstream
cluster API. This style is more compatible if you wish to manage the creation of all your Kubernetes
clusters through GitOps using something like [cluster-api](https://github.com/kubernetes-sigs/cluster-api)
or [Rancher](https://github.com/rancher/rancher).

101
docs/agent-initiated.md → docs/cluster-registration.md
View File

@ -3,13 +3,46 @@ import CodeBlock from '@theme/CodeBlock';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Agent Initiated
# Register Downstream Clusters
## Overview
There are two specific styles to registering clusters. These styles will be referred
to as **agent initiated** and **manager initiated** registration. Typically one would
go with the agent initiated registration but there are specific use cases in which
manager initiated is a better workflow.
### Agent Initiated Registration
Agent initiated refers to a pattern in which the downstream cluster installs an agent with a
[cluster registration token](#create-cluster-registration-tokens) and optionally a client ID. The cluster
agent will then make a API request to the Fleet manager and initiate the registration process. Using
this process the Manager will never make an outbound API request to the downstream clusters and will thus
never need to have direct network access. The downstream cluster only needs to make outbound HTTPS
calls to the manager.
### Manager Initiated Registration
Manager initiated registration is a process in which you register an existing Kubernetes cluster
with the Fleet manager and the Fleet manager will make an API call to the downstream cluster to
deploy the agent. This style can place additional network access requirements because the Fleet
manager must be able to communicate with the downstream cluster API server for the registration process.
After the cluster is registered there is no further need for the manager to contact the downstream
cluster API. This style is more compatible if you wish to manage the creation of all your Kubernetes
clusters through GitOps using something like [cluster-api](https://github.com/kubernetes-sigs/cluster-api)
or [Rancher](https://github.com/rancher/rancher).
## Agent Initiated
A downstream cluster is registered by installing an agent via helm and using the **cluster registration token** and optionally a **client ID** or **cluster labels**.
Refer to the [overview page](./cluster-overview.md#agent-initiated-registration) for a background information on the agent initiated registration style.
:::info
It's not necessary to configure the fleet manager for [multi cluster](./installation.md#configuration-for-multi-cluster), as the downstream agent we install via Helm will connect to the Kubernetes API of the upstream cluster directly.
## Cluster Registration Token and Client ID
Agent-initiated registration is normally not used with Rancher.
:::
### Cluster Registration Token and Client ID
The **cluster registration token** is a credential that will authorize the downstream cluster agent to be
able to initiate the registration process. This is required.
@ -20,11 +53,11 @@ There are two styles of registering an agent. You can have the cluster for this
case you will probably want to specify **cluster labels** upon registration. Or you can have the agent register to a predefined
cluster in the Fleet manager, in which case you will need a **client ID**. The former approach is typically the easiest.
## Install Agent For a New Cluster
### Install Agent For a New Cluster
The Fleet agent is installed as a Helm chart. Following are explanations how to determine and set its parameters.
First, follow the [cluster registration token page](./cluster-tokens.md) to obtain the `values.yaml` which contains
First, follow the [cluster registration token instructions](#create-cluster-registration-tokens) to obtain the `values.yaml` which contains
the registration token to authenticate against the Fleet cluster.
Second, optionally you can define labels that will assigned to the newly created cluster upon registration. After
@ -102,7 +135,7 @@ NAME BUNDLES-READY NODES-READY SAMPLE-NODE LAS
cluster-ab13e54400f1 1/1 1/1 k3d-cluster2-server-0 2020-08-31T19:23:10Z
```
## Install Agent For a Predefined Cluster
### Install Agent For a Predefined Cluster
Client IDs are for the purpose of predefining clusters in the Fleet manager with existing labels and repos targeted to them.
A client ID is not required and is just one approach to managing clusters.
@ -129,7 +162,7 @@ spec:
clientID: "really-random"
```
Second, follow the [cluster registration token page](./cluster-tokens.md) to obtain the `values.yaml` file to be used.
Second, follow the [cluster registration token instructions]((#create-cluster-registration-tokens) to obtain the `values.yaml` file to be used.
Third, setup your environment to use the client ID.
@ -188,7 +221,7 @@ NAME BUNDLES-READY NODES-READY SAMPLE-NODE LAS
my-cluster 1/1 1/1 k3d-cluster2-server-0 2020-08-31T19:23:10Z
```
## Cluster Registration Tokens
### Create Cluster Registration Tokens
:::info
@ -210,12 +243,12 @@ token after a successful registration please note that usually other system boot
Since the cluster registration token is forgotten, if you need to re-register a cluster you must
give the cluster a new registration token.
### Token TTL
#### Token TTL
Cluster registration tokens can be reused by any cluster in a namespace. The tokens can be given a TTL
such that it will expire after a specific time.
### Create a new Token
#### Create a new Token
The `ClusterRegistationToken` is a namespaced type and should be created in the same namespace
in which you will create `GitRepo` and `ClusterGroup` resources. For in depth details on how namespaces
@ -241,7 +274,7 @@ One way to do so is via the following one-liner:
while ! kubectl --namespace=clusters get secret new-token; do sleep 5; done
```
### Obtaining Token Value (Agent values.yaml)
#### Obtaining Token Value (Agent values.yaml)
The token value contains YAML content for a `values.yaml` file that is expected to be passed to `helm install`
to install the Fleet agent on a downstream cluster.
@ -253,3 +286,49 @@ kubectl --namespace clusters get secret new-token -o 'jsonpath={.data.values}' |
```
Once the `values.yaml` is ready it can be used repeatedly by clusters to register until the TTL expires.
## Manager Initiated
The manager initiated registration flow is accomplished by creating a
`Cluster` resource in the Fleet Manager that refers to a Kubernetes
`Secret` containing a valid kubeconfig file in the data field called `value`.
:::info
If you are using Fleet standalone *without Rancher*, it must be installed as described in [installation details](./installation.md#configuration-for-multi-cluster).
The manager-initiated registration is used when you add a cluster from the Rancher dashboard.
:::
### Create Kubeconfig Secret
The format of this secret is intended to match the [format](https://cluster-api.sigs.k8s.io/developer/architecture/controllers/cluster.html#secrets) of the kubeconfig
secret used in [cluster-api](https://github.com/kubernetes-sigs/cluster-api).
This means you can use `cluster-api` to create a cluster that is dynamically registered with Fleet.
```yaml title="Kubeconfig Secret Example"
kind: Secret
apiVersion: v1
metadata:
name: my-cluster-kubeconfig
namespace: clusters
data:
value: YXBpVmVyc2lvbjogdjEKY2x1c3RlcnM6Ci0gY2x1c3RlcjoKICAgIHNlcnZlcjogaHR0cHM6Ly9leGFtcGxlLmNvbTo2NDQzCiAgbmFtZTogY2x1c3Rlcgpjb250ZXh0czoKLSBjb250ZXh0OgogICAgY2x1c3RlcjogY2x1c3RlcgogICAgdXNlcjogdXNlcgogIG5hbWU6IGRlZmF1bHQKY3VycmVudC1jb250ZXh0OiBkZWZhdWx0CmtpbmQ6IENvbmZpZwpwcmVmZXJlbmNlczoge30KdXNlcnM6Ci0gbmFtZTogdXNlcgogIHVzZXI6CiAgICB0b2tlbjogc29tZXRoaW5nCg==
```
### Create Cluster Resource
The cluster resource needs to reference the kubeconfig secret.
```yaml title="Cluster Resource Example"
apiVersion: fleet.cattle.io/v1alpha1
kind: Cluster
metadata:
name: my-cluster
namespace: clusters
labels:
demo: "true"
env: dev
spec:
kubeConfigSecret: my-cluster-kubeconfig
```

6
docs/concepts.md
View File

@ -38,14 +38,14 @@ Below are some of the concepts of Fleet that will be useful throughout this docu
Regardless of the source the contents are dynamically rendered into a Helm chart by the agent
and installed into the downstream cluster as a helm release.
- To see the **lifecycle of a bundle**, click [here](./examples.md#lifecycle-of-a-fleet-bundle).
- To see the **life cycle of a bundle**, click [here](./ref-bundle-stages.md).
* **BundleDeployment**: When a `Bundle` is deployed to a cluster an instance of a `Bundle` is called a `BundleDeployment`.
A `BundleDeployment` represents the state of that `Bundle` on a specific cluster with its cluster specific
customizations. The Fleet agent is only aware of `BundleDeployment` resources that are created for
the cluster the agent is managing.
- For an example of how to deploy Kubernetes manifests across clusters using Fleet customization, click [here](./examples.md#deploy-kubernetes-manifests-across-clusters-with-customization).
- For an example of how to deploy Kubernetes manifests across clusters using Fleet customization, click [here](./gitrepo-targets.md#customization-per-cluster).
* **Downstream Cluster**: Clusters to which Fleet deploys manifests are referred to as downstream clusters. In the single cluster use case, the Fleet manager Kubernetes cluster is both the manager and downstream cluster at the same time.
* **Cluster Registration Token**: Tokens used by agents to register a new cluster.
* **Cluster Registration Token**: Tokens used by agents to register a new cluster.

8
docs/gitrepo-add.md
View File

@ -1,6 +1,6 @@
# Adding a GitRepo
# Create a GitRepo Resource
## Proper namespace
## Proper 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.
@ -18,9 +18,9 @@ If you are using Fleet in a [single cluster](./concepts.md) style, the namespace
For a [multi-cluster](./concepts.md) style, please ensure you use the correct repo that will map to the right target clusters.
## Create GitRepo instance
## Create GitRepo Instance
Git repositories are register by creating a `GitRepo` following the below YAML sample. Refer
Git repositories are registered by creating a `GitRepo` following the below YAML sample. Refer
to the inline comments as the means of each field
```yaml

6
docs/gitrepo-structure.md
View File

@ -1,4 +1,4 @@
# GitRepo Contents
# Git Repository Contents
Fleet will create bundles from a git repository. This happens either explicitly by specifying paths, or when a `fleet.yaml` is found.
@ -243,7 +243,7 @@ dependsOn:
### Private Helm Repositories
For a private Helm repo, users can reference a secret from the git repo resource.
See [Using Private Helm Repositories](gitrepo-add#using-private-helm-repositories) for more information.
See [Using Private Helm Repositories](./gitrepo-add.md#using-private-helm-repositories) for more information.
### Using ValuesFrom
@ -336,6 +336,6 @@ will target `deployment.yaml`. The patch will be applied using JSON Merge, Stra
Which strategy is used is based on the file content. Even though JSON strategies are used, the files can be written
using YAML syntax.
## Cluster and Bundle state
## Cluster and Bundle State
See [Cluster and Bundle state](./cluster-bundles-state.md).

8
docs/installation.md
View File

@ -35,7 +35,7 @@ use case for production.
</TabItem>
</Tabs>
## Install
## Default Install
Install the following two Helm charts.
@ -85,7 +85,7 @@ The multi-cluster install described below is **only** covered in standalone Flee
The setup is the same as for a single cluster.
After installing the Fleet manager, you will then need to register remote downstream clusters with the Fleet manager.
However, to allow for [manager-initiated registration](./manager-initiated) of downstream clusters, a few extra settings are required. Without the API server URL and the CA, only [agent-initiated registration](./agent-initiated) of downstream clusters is possible.
However, to allow for [manager-initiated registration](./cluster-registration.md#manager-initiated) of downstream clusters, a few extra settings are required. Without the API server URL and the CA, only [agent-initiated registration](./cluster-registration.md#agent-initiated) of downstream clusters is possible.
:::
### API Server URL and CA certificate
@ -186,7 +186,7 @@ KDs/pb3fnMTtpA==
-----END CERTIFICATE-----
```
### Install
### Install for Multi-Cluster
In the following example it will be assumed the API server URL from the `KUBECONFIG` which is `https://example.com:6443`
and the CA certificate is in the file `ca.pem`. If your API server URL is signed by a well-known CA you can
@ -234,5 +234,5 @@ fleet-controller-64f49d756b-n57wq 1/1 Running 0 3m21s
</TabItem>
</Tabs>
At this point the Fleet manager should be ready. You can now [register clusters](./cluster-overview.md) and [git repos](./gitrepo-add.md) with
At this point the Fleet manager should be ready. You can now [register clusters](./cluster-registration.md) and [git repos](./gitrepo-add.md#create-gitrepo-instance) with
the Fleet manager.

49
docs/manager-initiated.md
View File

@ -1,49 +0,0 @@
# Manager Initiated
Refer to the [overview page](./cluster-overview.md#agent-initiated-registration) for a background information on the manager initiated registration style.
If you are using Fleet standalone without Rancher, it must be installed as described in [installation details](installation.md).
## Kubeconfig Secret
The manager initiated registration flow is accomplished by creating a
`Cluster` resource in the Fleet Manager that refers to a Kubernetes
`Secret` containing a valid kubeconfig file in the data field called `value`.
The format of this secret is intended to match the [format](https://cluster-api.sigs.k8s.io/developer/architecture/controllers/cluster.html#secrets)
of the kubeconfig
secret used in [cluster-api](https://github.com/kubernetes-sigs/cluster-api).
This means you can use `cluster-api` to create a cluster that is dynamically
registered with Fleet.
## Example
### Kubeconfig Secret
```yaml
kind: Secret
apiVersion: v1
metadata:
name: my-cluster-kubeconfig
namespace: clusters
data:
value: YXBpVmVyc2lvbjogdjEKY2x1c3RlcnM6Ci0gY2x1c3RlcjoKICAgIHNlcnZlcjogaHR0cHM6Ly9leGFtcGxlLmNvbTo2NDQzCiAgbmFtZTogY2x1c3Rlcgpjb250ZXh0czoKLSBjb250ZXh0OgogICAgY2x1c3RlcjogY2x1c3RlcgogICAgdXNlcjogdXNlcgogIG5hbWU6IGRlZmF1bHQKY3VycmVudC1jb250ZXh0OiBkZWZhdWx0CmtpbmQ6IENvbmZpZwpwcmVmZXJlbmNlczoge30KdXNlcnM6Ci0gbmFtZTogdXNlcgogIHVzZXI6CiAgICB0b2tlbjogc29tZXRoaW5nCg==
```
### Cluster
```yaml
apiVersion: fleet.cattle.io/v1alpha1
kind: Cluster
metadata:
name: my-cluster
namespace: clusters
labels:
demo: "true"
env: dev
spec:
kubeConfigSecret: my-cluster-kubeconfig
```

6
docs/multi-tenancy.md
View File

@ -2,7 +2,7 @@
Fleet uses Kubernetes RBAC where possible.
One addition on top of RBAC is the [`GitRepoRestriction`](namespaces#restricting-gitrepos) resource, which can be used to control GitRepo resources in a namespace.
One addition on top of RBAC is the [`GitRepoRestriction`](./namespaces.md#restricting-gitrepos) resource, which can be used to control GitRepo resources in a namespace.
A multi-tenant fleet setup looks like this:
@ -35,7 +35,7 @@ This makes sure, tenants can't interfere with GitRepo resources from other tenan
This assumes all GitRepos created by 'fleetuser' have the `team: one` label. Different labels could be used, to select different cluster namespaces.
In each of the user's namespaces, as an admin create a [`BundleNamespaceMapping`](./namespaces#cross-namespace-deployments).
In each of the user's namespaces, as an admin create a [`BundleNamespaceMapping`](./namespaces.md#cross-namespace-deployments).
kind: BundleNamespaceMapping
apiVersion: fleet.cattle.io/v1alpha1
@ -59,7 +59,7 @@ In each of the user's namespaces, as an admin create a [`BundleNamespaceMapping`
# the label is on the namespace
#workspace: prod
The [`target` section](./gitrepo-targets) in the GitRepo resource can be used to deploy only to a subset of the matched clusters.
The [`target` section](./gitrepo-targets.md) in the GitRepo resource can be used to deploy only to a subset of the matched clusters.
## Restricting Access to Downstream Clusters

2
docs/namespaces.md
View File

@ -18,7 +18,7 @@ When deploying a Fleet bundle, the specified namespace will automatically be cre
## Special Namespaces
An overview of the [namespaces](namespaces.md) used by fleet and their resources.
An overview of the [namespaces](./namespaces.md) used by fleet and their resources.
![Namespace](/img/FleetNamespaces.svg)

11
sidebars.js
View File

@ -19,7 +19,6 @@ module.exports = {
'architecture',
'concepts',
'ref-bundle-stages',
'ref-components',
'namespaces',
'ref-resources',
],
@ -30,14 +29,7 @@ module.exports = {
collapsed: false,
items:[
{type: 'doc', id: 'installation'},
{
'Registering Clusters':
[
{type: 'doc', id: 'cluster-overview'},
{type: 'doc', id: 'agent-initiated'},
{type: 'doc', id: 'manager-initiated'},
],
},
{type: 'doc', id: 'cluster-registration'},
{type:'doc', id:'cluster-group'},
'multi-tenancy',
],
@ -77,6 +69,7 @@ module.exports = {
{type:'doc', id:'cluster-bundles-state'},
'ref-registration',
'ref-configuration',
'ref-components',
"ref-crds",
'ref-fleet-yaml',
'ref-crd-gitrepo',