diff --git a/docs/architecture.md b/docs/architecture.md index b104ba92a..3a5d358a5 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -41,4 +41,4 @@ subresource of it's `Cluster` resource. An overview of the components and how they interact on a high level. -![Components](/img/FleetComponents.svg) +![Components](../static/img/FleetComponents.svg) diff --git a/docs/bundle-add.md b/docs/bundle-add.md index 2012f5791..0d365f65f 100644 --- a/docs/bundle-add.md +++ b/docs/bundle-add.md @@ -88,30 +88,6 @@ You can't use a `fleet.yaml` in resources, it is only used by the fleet-cli to c The `spec.targetRestrictions` field is not useful, as it is an allow list for targets specified in `spec.targets`. It is not needed, since `targets` are explicitly given in a bundle and an empty `targetRestrictions` defaults to allow. -## Convert a Helm Chart into a Bundle - -You can use the Fleet CLI to convert a Helm chart into a bundle. - -For example, you can download and convert the "external secrets" operator chart like this: -``` -cat > targets.yaml < app/fleet.yaml < eso-bundle.yaml - -kubectl apply -f eso-bundle.yaml -``` - -Make sure you use a cluster selector in `targets.yaml`, that matches all clusters you want to deploy to. - -The blog post on [Fleet: Multi-Cluster Deployment with the Help of External Secrets](https://www.suse.com/c/rancher_blog/fleet-multi-cluster-deployment-with-the-help-of-external-secrets/) has more information. +:::note +You can use Fleet CLI to convert a Helm chart into a `bundle`. For more information, refer to [Convert a Helm chart into a bundle using CLI.](install-usage-fleetCLI.md#convert-a-helm-chart-into-a-bundle). +::: \ No newline at end of file diff --git a/docs/bundle-diffs.md b/docs/bundle-diffs.md index 30d427772..3ef1174fd 100644 --- a/docs/bundle-diffs.md +++ b/docs/bundle-diffs.md @@ -11,10 +11,10 @@ The bundled charts may have some objects that are amended at runtime, for exampl This leads the status of the bundle and associated GitRepo to be reported as "Modified" -![](/img/ModifiedGitRepo.png) +![](../static/img/ModifiedGitRepo.png) Associated Bundle -![](/img/ModifiedBundle.png) +![](../static/img/ModifiedBundle.png) Fleet bundles support the ability to specify a custom [jsonPointer patch](http://jsonpatch.com/). @@ -146,7 +146,7 @@ In summary, we need to ignore the fields `rules` and `clientConfig.caBundle` in The field webhook in the ValidatingWebhookConfiguration spec is an array, so we need to address the elements by their index values. -![](/img/WebhookConfigurationSpec.png) +![](../static/img/WebhookConfigurationSpec.png) Based on this information, our diff patch would look as follows: diff --git a/docs/cli/fleet-cli/install_fleet.md b/docs/cli/fleet-cli/install_fleet.md deleted file mode 100644 index f8040502e..000000000 --- a/docs/cli/fleet-cli/install_fleet.md +++ /dev/null @@ -1,156 +0,0 @@ -# Fleet CLI - -Fleet CLI is a command-line interface(CLI) that allows you to interact directly with Fleet from your local machine. It enables you to create, apply and inspect `bundles` without requiring a `GitRepo`. Typical use cases include: - -* Testing and previewing `bundle` contents. -* Creating bundles directly from Helm charts, Kubernetes manifests and `fleet.yaml` files. -* Checking which clusters a `bundle` would target -* Validating deployments without installing Fleet in the cluster - -:::note -You can use `fleet apply` without installing Fleet in your clusters. However, for cluster interaction (for example, `fleet target`, `fleet deploy`), Fleet must be installed. For more information, refer to [Install Fleet.](../../installation.md) -::: - -## Install Fleet CLI - -Fleet CLI is a stand-alone binary you can download from the [Fleet GitHub releases page](https://github.com/rancher/fleet/releases). - -**Linux/macOS** - -```bash -curl -L -o fleet https://github.com/rancher/fleet/releases/download/v0.12.4/fleet-linux-amd64 - -# Make it executable and move to PATH - -chmod +x fleet - -sudo mv fleet /usr/local/bin/ -``` - -**Windows (PowerShell)** - -```bash -Invoke-WebRequest -Uri "https://github.com/rancher/fleet/releases/download/v0.12.4/fleet-windows-amd64.exe" -OutFile "fleet.exe" -``` - -**Verify installation** - -```bash -fleet --version -``` - -## **Prerequisites** - -Make sure you have the following tools installed and configured: - -* A working Kubernetes cluster (e.g., via k3s, kind, or a cloud provider). -* `kubectl` is configured for your cluster. -* helm is installed. -* Fleet CLI is installed and accessible in your terminal. - -**Verify prerequisites** - -```bash -kubectl get nodes -helm version -fleet --version -``` - -## Key commands - -* `fleet target`: Displays which clusters would receive a bundle based on selectors and targeting rules. - * This helps you understand how `targets`, `targetOverrides`, `clusterGroups`, and `label` selectors work. For example, `fleet target my-bundle ./manifests.` -* `fleet deploy`: Deploy a `bundle` with or without pushing it to the cluster. - * Supports dry-run mode to preview changes applied. For example, `fleet deploy --dry-run my-bundle ./manifests`. -* `fleet apply`: Create or preview a `Bundle` from local files. Works without Fleet installed. - * This applies for `fleet.yaml`, Helm charts and manifests. For example, `fleet apply my-bundle ./manifests`. - -![A diagram explaining how fleet CLI key commands work.](/img/fleetCLI-key-components.svg) - -For more information, refer to [Bundle Lifecycle With the CLI](../../ref-bundle-stages.md#examining-the-bundle-lifecycle-with-the-cli). - -## Deploy a Sample Bundle Using Fleet CLI - -You can deploy workloads without using GitRepos by applying them locally with the CLI. For example, consider using the [Fleet examples repository](https://github.com/rancher/fleet-examples). - -```bash -git clone https://github.com/rancher/fleet-examples -cd fleet-examples/single-cluster/manifests -``` - -Apply it to the current cluster: - -```bash -fleet apply deployments . -fleet apply services. -fleet apply nginx-bundle . -``` - -This creates a Bundle resource named `nginx-bundle`, `deployments` and `services` in the namespace. - -![A screenshot of deploying a sample bundle.](/img/apply-fleet-ss.png) - -### Validate the Deployment - -After applying a bundle using Fleet CLI, you can validate the deployment by inspecting the `Bundle` and its associated `BundleDeployments`. - -Each Fleet-managed cluster lists: - -* Which bundles are deployed to it. -* Their readiness status. -* Errors or sync issues (if any). - -To validate whether your `fleet apply` created a `bundle` and if it’s deployed to the right number of target(s), run: - -```bash -kubectl get bundles.fleet.cattle.io -A -``` - -![A screenshot validating the fleet deployment.](/img/validate-deployment-ss.png) - -You see the following fields: - -* `BUNDLEDEPLOYMENTS-READY` shows how many targets are ready out of the total. -* `STATUS` may show Ready, Modified, or other conditions based on the `rollout`. - -:::note: -If this field shows 1/1, the bundle is successfully deployed to one cluster. -::: - -To get a detailed view of how the bundle was rendered and applied: - -`kubectl get bundles.fleet.cattle.io -n fleet-local my-nginx-bundle -o yaml` - -Look for the following fields in the `status` section: - -```yaml -status: - display: - readyClusters: 1/1 - summary: - desiredReady: 1 - ready: 1 - conditions: - type: Ready - status: "True" -``` - -This indicates that: - -* The bundle was scheduled for 1 cluster. -* The target cluster has acknowledged and applied the resources. -* The controller marked the deployment as ready. - -You can also verify the corresponding `BundleDeployment` object, since each `BundleDeployment` corresponds to a target cluster. - -`kubectl get bundledeployments.fleet.cattle.io -A` - -## **Troubleshooting** - -If the bundle is not ready: - -* Check if `fleet-controller` and `fleet-agent` pods are running. -* Make sure the `fleet-local` cluster is registered: -* Inspect the bundle for error messages: - * `kubectl describe bundle -n fleet-local nginx-bundle` -* Delete and re-apply the bundle if you encounter Helm ownership conflicts. diff --git a/docs/gitrepo-content.md b/docs/gitrepo-content.md index 275e23a91..f8ca3cf7e 100644 --- a/docs/gitrepo-content.md +++ b/docs/gitrepo-content.md @@ -200,7 +200,7 @@ __How changes are applied to `values.yaml`__: - When changes are applied to the `values.yaml` from multiple sources at the same time, the values will update in the following order: `helm.values` -> `helm.valuesFiles` -> `helm.valuesFrom`. That means `valuesFrom` will take precedence over both, `valuesFiles` and `values`. -![](/img/FleetValuesStages.svg) +![](../static/img/FleetValuesStages.svg) The targeting step can treat the values as a template and fill in information from the `clusters.fleet.cattle.io` resource. More information can be found in [Helm values templating](./ref-fleet-yaml#values-templating). This can be turned off in `fleet.yaml`, by setting `disablePreProcess`, e.g. to avoid conflicts with other templating languages. diff --git a/docs/index.md b/docs/index.md index d5d90ae2f..643239072 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ # Overview -![](/img/fleet-architecture.svg) +![](../static/img/fleet-architecture.svg) ### What is Fleet? diff --git a/docs/install-usage-fleetCLI.md b/docs/install-usage-fleetCLI.md new file mode 100644 index 000000000..dcbd470a8 --- /dev/null +++ b/docs/install-usage-fleetCLI.md @@ -0,0 +1,131 @@ +# Install and Use Fleet CLI + +Fleet CLI is a command-line interface(CLI) that allows you to interact directly with Fleet from your local machine. It enables you to create, apply and inspect `bundles` without requiring a `GitRepo`. Typical use cases include: + +* Testing and previewing `bundle` contents. +* Creating bundles directly from Helm charts, Kubernetes manifests and `fleet.yaml` files. +* Checking which clusters a `bundle` would target +* Validating deployments without installing Fleet in the cluster + +:::note +You can use `fleet apply` without installing Fleet in your clusters. However, for cluster interaction (for example, `fleet target`, `fleet deploy`), Fleet must be installed. For more information, refer to [Install Fleet.](installation.md) +::: + +## Install Fleet CLI + +Fleet CLI is a stand-alone binary you can download from the [Fleet GitHub releases page](https://github.com/rancher/fleet/releases). + +**Linux/macOS** + +```bash +curl -L -o fleet https://github.com/rancher/fleet/releases/download/v0.12.4/fleet-linux-amd64 + +# Make it executable and move to PATH + +chmod +x fleet + +sudo mv fleet /usr/local/bin/ +``` + +**Windows (PowerShell)** + +```bash +Invoke-WebRequest -Uri "https://github.com/rancher/fleet/releases/download/v0.12.4/fleet-windows-amd64.exe" -OutFile "fleet.exe" +``` + +**Verify installation** + +```bash +fleet --version +``` + +## **Prerequisites** + +Make sure you have the following tools installed and configured: + +* A working Kubernetes cluster (e.g., via k3s, kind, or a cloud provider). +* `kubectl` is configured for your cluster. +* helm is installed. +* Fleet CLI is installed and accessible in your terminal. + +**Verify prerequisites** + +```bash +kubectl get nodes +helm version +fleet --version +``` + +## Key commands + +Fleet provides several CLI commands to create, preview, and deploy bundles. These commands are useful for debugging and understanding the bundle lifecycle. + +* `fleet target`: Reads a bundle file and evaluates which clusters would receive it, based on selectors and targeting rules such as `targets`, `targetOverrides`, `clusterGroups`, and `label` selectors. + * For example, `fleet target my-bundle ./manifests.` +* `fleet apply`: creates or previews a `bundle` from local files, such as a Helm chart, Kubernetes manifests, or kustomize folders. This command works even without Fleet installed. + * This applies for `fleet.yaml`, Helm charts and manifests. For example, `fleet apply my-bundle ./manifests`. +* `fleet deploy`: deploys a `bundle` with or without pushing it to the cluster. You can use it with the output of fleet target or a dumped bundledeployment/content resource. You can use it for: + * `fleet apply -o - name ./folder` to check the YAML of the bundle before creating it. For more information, refer to as in [Convert a Helm chart into a bundle.](#convert-a-helm-chart-into-a-bundle) + * Target to debug selectors and verify which downstream clusters are targeted. + * `fleet deploy --dry-run` to validate workload resources. + +![A diagram explaining how fleet CLI key commands work.](../static/img/fleetCLI-key-components.svg) + +For more information, refer to [Bundle Lifecycle With the CLI](ref-bundle-stages.md#examining-the-bundle-lifecycle-with-the-cli). + +## Deploy a Sample Bundle Using Fleet CLI + +You can deploy workloads without using GitRepos by applying them locally with the CLI. For example, consider using the [Fleet examples repository](https://github.com/rancher/fleet-examples). + +```bash +git clone https://github.com/rancher/fleet-examples +cd fleet-examples/single-cluster +``` + +Apply it to the current cluster: + +```bash +fleet apply -o my-cool-bundle manifests +``` + +This creates a Bundle resource in the namespace. + +## Convert a Helm Chart into a Bundle + +You can use the Fleet CLI to convert a Helm chart into a bundle. + +For example, you can download and convert the "external secrets" operator chart like this: + +```bash +cat > targets.yaml < app/fleet.yaml < eso-bundle.yaml + +kubectl apply -f eso-bundle.yaml +``` + +Make sure you use a cluster selector in `targets.yaml`, that matches all clusters you want to deploy to. + +The blog post on [Fleet: Multi-Cluster Deployment with the Help of External Secrets](https://www.suse.com/c/rancher_blog/fleet-multi-cluster-deployment-with-the-help-of-external-secrets/) has more information. + + +## **Troubleshooting** + +If the bundle is not ready: + +* Check if `fleet-controller` and `fleet-agent` pods are running. +* Make sure the `fleet-local` cluster is registered: +* Inspect the bundle for error messages: + * `kubectl describe bundle -n fleet-local nginx-bundle` +* Delete and re-apply the bundle if you encounter Helm ownership conflicts. diff --git a/docs/installation.md b/docs/installation.md index 0ca7b1a48..8fcaefce4 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -13,7 +13,7 @@ you will setup a centralized manager cluster to which you can register clusters. If you are just learning Fleet the single cluster install is the recommended starting point. After which you can move from single cluster to multi-cluster setup down the line. -![](/img/single-cluster.png) +![](../static/img/single-cluster.png) Single-cluster is the default installation. The same cluster will run both the Fleet manager and the Fleet agent. The cluster will communicate with Git server to diff --git a/docs/multi-user.md b/docs/multi-user.md index 4a839d1c3..dd59691ff 100644 --- a/docs/multi-user.md +++ b/docs/multi-user.md @@ -12,7 +12,7 @@ A multi-user fleet setup looks like this: namespaces on downstream clusters * clusters are in a separate namespace -![Shared Clusters](/img/FleetSharedClusters.svg) +![Shared Clusters](../static/img/FleetSharedClusters.svg) :::warning important information diff --git a/docs/namespaces.md b/docs/namespaces.md index 0210d81d0..759e5966c 100644 --- a/docs/namespaces.md +++ b/docs/namespaces.md @@ -22,7 +22,7 @@ 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. -![Configuring Workload Namespaces](/img/FleetWorkloadNamespaces.png) +![Configuring Workload Namespaces](../static/img/FleetWorkloadNamespaces.png) ### Cross Namespace Deployments @@ -106,7 +106,7 @@ 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) +![Namespace](../static/img/FleetNamespaces.svg) ### GitRepos, Bundles, Clusters, ClusterGroups diff --git a/docs/quickstart.md b/docs/quickstart.md index 12ed8d0f2..88c12dadd 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -5,7 +5,7 @@ import TabItem from '@theme/TabItem'; # Quick Start -![](/img/single-cluster.png) +![](../static/img/single-cluster.png) Who needs documentation, lets just run this thing! diff --git a/docs/ref-bundle-stages.md b/docs/ref-bundle-stages.md index 05d0e7ade..4332c457c 100644 --- a/docs/ref-bundle-stages.md +++ b/docs/ref-bundle-stages.md @@ -16,12 +16,14 @@ To demonstrate the life cycle of a Fleet bundle, we will use [multi-cluster/helm This diagram shows the different rendering stages a bundle goes through until deployment. -![Bundle Stages](/img/FleetBundleStages.svg) +![Bundle Stages](../static/img/FleetBundleStages.svg) ## Examining the Bundle Lifecycle With the CLI Several fleet CLI commands help with debugging bundles. +![A diagram explaining how fleet CLI key commands work.](../static/img/fleetCLI-key-components.svg) + ### fleet apply [Apply](./cli/fleet-cli/fleet_apply.md) renders a folder with Kubernetes resources, such as a Helm chart, manifests, or kustomize folders, into a Fleet bundle resource. @@ -34,19 +36,11 @@ fleet apply -n fleet-local -o bundle.yaml testbundle simple-chart/ More information on how to create bundles with `fleet apply` can be found in the [section on bundles](https://fleet.rancher.io/bundle-add). -### fleet target +### Lifecycle CLI -[Target](./cli/fleet-cli/fleet_target.md) reads a bundle from a file and works with a live cluster to print out the `bundledeployment` & `content` resource, which fleetcontroller would create. It takes a namespace as an argument, so it can look in that namespace for e.g. cluster resources. It can also dump the data structure which is used during "targeting", so decisions taken regarding labels and cluster names can be checked. +Fleet CLI commands help you debug and understand the bundle lifecycle. The following example uses the full bundle lifecycle using CLI: -### fleet deploy - -[Deploy](./cli/fleet-cli/fleet_deploy.md) takes the output of `fleet target`, or a dumped bundledeployment/content resource and deploys it to a cluster, just like fleet-agent would. It supports a dry run mode, to print out the resources which would be created, instead of installing them with helm. Since the command doesn't create the input resources, a running fleet-agent would likely garbage collect the deployment. - -The deploy command can be used to bring bundles to air-gapped clusters. - -### Lifecycle CLI Example - -``` +```bash git clone https://github.com/rancher/fleet-test-data cd fleet-test-data # for information about apply see https://fleet.rancher.io/bundle-add @@ -54,3 +48,5 @@ fleet apply -n fleet-local -o bundle.yaml testbundle simple-chart/ fleet target --bundle-file bundle.yaml --dump-input-list > bd.yaml fleet deploy --input-file bd.yaml --dry-run ``` + +For more information, refer to [Fleet CLI Key commands.](install-usage-fleetCLI.md#key-commands) \ No newline at end of file diff --git a/docs/ref-registration.md b/docs/ref-registration.md index 2125bacae..5c1f0f166 100644 --- a/docs/ref-registration.md +++ b/docs/ref-registration.md @@ -42,7 +42,7 @@ The Fleet controller triggers and tries to grant the `ClusterRegistration` reque The new kubeconfig uses the "request" account. The "request" account can access the cluster status, `BundleDeployments` and `Contents`. -![ClusterRegistationToken to ClusterRegistration](/img/FleetRegistrationToken.svg) +![ClusterRegistationToken to ClusterRegistration](../static/img/FleetRegistrationToken.svg) ### Fleet Agent is Registered, Watches for `BundleDeployments` @@ -73,7 +73,7 @@ It is important to note that there are multiple ways to start this: * Creating a `Cluster` resource with a kubeconfig. Rancher does this for downstream clusters. See [manager-initiated registration](./cluster-registration.md#manager-initiated). * Create a `ClusterRegistrationToken` resource, optionally create a `Cluster` resource for a pre-defined (`clientID`) cluster. See [agent-initiated registration](./cluster-registration.md#agent-initiated). -![Registration](/img/FleetRegistration.svg) +![Registration](../static/img/FleetRegistration.svg) ### Secrets during Agent Deployment @@ -94,7 +94,7 @@ contains the upstream server URL and CA, next to the downstream's kubeconfig. If the settings are present in the kubeconfig secret, they override the configured values. -![Registration Secrets](/img/FleetRegistrationSecrets.svg) +![Registration Secrets](../static/img/FleetRegistrationSecrets.svg) ## Fleet Cluster Registration in Rancher diff --git a/docs/ref-status-fields.md b/docs/ref-status-fields.md index 4fa82aab6..96421610d 100644 --- a/docs/ref-status-fields.md +++ b/docs/ref-status-fields.md @@ -284,7 +284,7 @@ Similarly to what happens for `GitRepos`, the deployed resources are listed in ## Resource Counts This shows how resource counts are propagated from one resource to another: -![Status Propagation](/img/FleetStatusSource.png) +![Status Propagation](../static/img/FleetStatusSource.png) ### GitRepos diff --git a/docs/resources-during-deployment.md b/docs/resources-during-deployment.md index 2373eb55f..96373ef6c 100644 --- a/docs/resources-during-deployment.md +++ b/docs/resources-during-deployment.md @@ -2,4 +2,4 @@ This shows the resources, also the internal ones, involved in creating a deployment from a git repository. -![Resources](/img/FleetResources.svg) +![Resources](../static/img/FleetResources.svg) diff --git a/docs/validate-fleetCLI.md b/docs/validate-fleetCLI.md new file mode 100644 index 000000000..6fbe686cd --- /dev/null +++ b/docs/validate-fleetCLI.md @@ -0,0 +1,56 @@ +# Validate Fleet CLI Deployment + +After applying a bundle using Fleet CLI, you can validate the deployment by inspecting the `Bundle` and its associated `BundleDeployments`. + +Each Fleet-managed cluster lists: + +* Which bundles are deployed to it. +* Their readiness status. +* Errors or sync issues (if any). + +To validate whether your `fleet apply` created a `bundle` and if it’s deployed to the right number of target(s), run: + +```bash +kubectl get bundles.fleet.cattle.io -A +``` + +![A screenshot validating the fleet deployment.](../static/img/validate-deployment-ss.png) + +You see the following fields: + +* `BUNDLEDEPLOYMENTS-READY` shows how many targets are ready out of the total. +* `STATUS` may show Ready, Modified, or other conditions based on the `rollout`. + +:::note: +If this field shows 1/1, the bundle is successfully deployed to one cluster. +::: + +To get a detailed view of how the bundle was rendered and applied: + +`kubectl get bundles.fleet.cattle.io -n fleet-local my-nginx-bundle -o yaml` + +Look for the following fields in the `status` section: + +```yaml +status: + display: + readyClusters: 1/1 + summary: + desiredReady: 1 + ready: 1 + conditions: + type: Ready + status: "True" +``` + +This indicates that: + +* The bundle was scheduled for 1 cluster. +* The target cluster has acknowledged and applied the resources. +* The controller marked the deployment as ready. + +You can also verify the corresponding `BundleDeployment` object, since each `BundleDeployment` corresponds to a target cluster. + +`kubectl get bundledeployments.fleet.cattle.io -A` + +For more information, refer to [Status Fields](ref-status-fields.md). diff --git a/docs/webhook.md b/docs/webhook.md index 0b58f055e..19b34d4d0 100644 --- a/docs/webhook.md +++ b/docs/webhook.md @@ -61,7 +61,7 @@ You can configure [TLS](https://kubernetes.io/docs/concepts/services-networking/ ### 2. Go to your webhook provider and configure the webhook callback url. Here is a Github example. -![](/img/webhook.png) +![](../static/img/webhook.png) Configuring a secret is optional. This is used to validate the webhook payload as the payload should not be trusted by default. If your webhook server is publicly accessible to the Internet, then it is recommended to configure the secret. If you do configure the diff --git a/sidebars.js b/sidebars.js index 5b410c5c7..e410ae9ad 100644 --- a/sidebars.js +++ b/sidebars.js @@ -9,6 +9,8 @@ module.exports = { items:[ 'quickstart', 'tut-deployment', + 'install-usage-fleetCLI', + 'validate-fleetCLI', {type:'doc', id:'uninstall'}, ], }, diff --git a/static/img/apply-fleet-ss.png b/static/img/apply-fleet-ss.png deleted file mode 100644 index 93ca4558d..000000000 Binary files a/static/img/apply-fleet-ss.png and /dev/null differ