From 1fd7aba7058185da5d1c630f66cbca6348b03690 Mon Sep 17 00:00:00 2001 From: raul Date: Mon, 15 May 2023 13:37:31 +0200 Subject: [PATCH] Add documention for Bundles --- docs/bundle-add.md | 57 ++++++++++++++++++++++++++++ docs/ref-bundle.md | 94 ++++++++++++++++++++++++++++++++++++++++++++++ sidebars.js | 2 + 3 files changed, 153 insertions(+) create mode 100644 docs/bundle-add.md create mode 100644 docs/ref-bundle.md diff --git a/docs/bundle-add.md b/docs/bundle-add.md new file mode 100644 index 000000000..7c66744cb --- /dev/null +++ b/docs/bundle-add.md @@ -0,0 +1,57 @@ +# Create a Bundle Resource + +Bundles are automatically created by Fleet when a `GitRepo` is created. In most cases `Bundles` should not be created +manually by the user. If you want to deploy resources from a git repository use a +[GitRepo](https://fleet.rancher.io/gitrepo-add) instead. + +If you want to deploy resources without a git repository follow this guide to create a `Bundle`. + +When creating a `GitRepo` Fleet will fetch the resources from a git repository, and add them to a Bundle. +When creating a `Bundle` resources need to be explicitly specified in the `Bundle` Spec. +Resources can be compressed with gz. See [here](https://github.com/rancher/rancher/blob/v2.7.3/pkg/controllers/provisioningv2/managedchart/managedchart.go#L149-L153) +an example of how Rancher uses compression in go code. + +If you would like to deploy in downstream clusters, you need to define targets. Targets work similarly to targets in `GitRepo`. +See [Mapping to Downstream Clusters](https://fleet.rancher.io/gitrepo-targets#defining-targets). + +The following example creates a nginx `Deployment` in the local cluster: + +```yaml +kind: Bundle +apiVersion: fleet.cattle.io/v1alpha1 +metadata: + # Any name can be used here + name: my-bundle + # For single cluster use fleet-local, otherwise use the namespace of + # your choosing + namespace: fleet-local +spec: + resources: + # List of all resources that will be deployed + - content: | + apiVersion: apps/v1 + kind: Deployment + metadata: + name: nginx-deployment + labels: + app: nginx + spec: + replicas: 3 + selector: + matchLabels: + app: nginx + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx:1.14.2 + ports: + - containerPort: 80 + name: nginx.yaml + targets: + - clusterName: local + +``` diff --git a/docs/ref-bundle.md b/docs/ref-bundle.md new file mode 100644 index 000000000..518059c70 --- /dev/null +++ b/docs/ref-bundle.md @@ -0,0 +1,94 @@ +# Bundle Resource + +Bundles are automatically created by Fleet when a `GitRepo` is created. + +The content of the resource corresponds to the [BundleSpec](./ref-crds#bundlespec). +For more information on how to use the Bundle resource [Create a Bundle Resource](./bundle-add.md). + +```yaml +kind: Bundle +apiVersion: fleet.cattle.io/v1alpha1 +metadata: + # Any name can be used here + name: my-bundle + # For single cluster use fleet-local, otherwise use the namespace of + # your choosing + namespace: fleet-local +spec: + # Namespace used for resources that do not specify a namespace. + # This field is not used to enforce or lock down the deployment to a specific namespace. + # defaultNamespace: test + + # If present will assign all resource to this + # namespace and if any cluster scoped resource exists the deployment will fail. + # targetNamespace: app + + # Kustomize options for the deployment, like the dir containing the kustomization.yaml file. + # kustomize: ... + + # Helm options for the deployment, like the chart name, repo and values. + # helm: ... + + # ServiceAccount which will be used to perform this deployment. + # serviceAccount: sa + + # ForceSyncGeneration is used to force a redeployment. + # forceSyncGeneration: 0 + + # YAML options, if using raw YAML these are names that map to overlays/{name} that will be used to replace or patch a resource. + # yaml: ... + + # Diff can be used to ignore the modified state of objects which are amended at runtime. + # A specific commit or tag can also be watched. + # + # diff: ... + + # KeepResources can be used to keep the deployed resources when removing the bundle. + # keepResources: false + + # If set to true, will stop any BundleDeployments from being updated. It will be marked as out of sync. + # paused: false + + # Controls the rollout of bundles, by defining partitions, canaries and percentages for cluster availability. + # rolloutStrategy: ... + + # Contain the actual resources from the git repo which will be deployed. + resources: + - content: | + apiVersion: apps/v1 + kind: Deployment + metadata: + name: nginx-deployment + labels: + app: nginx + spec: + replicas: 3 + selector: + matchLabels: + app: nginx + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx:1.14.2 + ports: + - containerPort: 80 + name: nginx.yaml + + # Target clusters to deploy to if running Fleet in a multi-cluster + # style. Refer to the "Mapping to Downstream Clusters" docs for + # more information. + # + # targets: ... + + # This field is used by Fleet internally, and it should not be modified manually. + # Fleet will copy all targets into targetRestrictions when a Bundle is created for a GitRepo. + # targetRestrictions: ... + + # Refers to the bundles which must be ready before this bundle can be deployed. + # dependsOn: ... + +``` diff --git a/sidebars.js b/sidebars.js index 6f4c952c4..b4b530d48 100644 --- a/sidebars.js +++ b/sidebars.js @@ -45,6 +45,7 @@ module.exports = { {type:'doc', id:'bundle-diffs'}, {type:'doc', id:'webhook'}, {type:'doc', id:'imagescan'}, + {type:'doc', id:'bundle-add'}, ], }, { @@ -72,6 +73,7 @@ module.exports = { "ref-crds", 'ref-fleet-yaml', 'ref-gitrepo', + 'ref-bundle', ], }, 'troubleshooting',