Packages:
+ +templates.weave.works/v1alpha1
+Package v1alpha1 contains API Schema definitions for the gitopssets v1alpha1 API group
+Resource Types: +- +GitOpsSet +
GitOpsSet +
+GitOpsSet is the Schema for the gitopssets API
+| Field | +Description | +||||||||
|---|---|---|---|---|---|---|---|---|---|
+apiVersion+string |
+
+templates.weave.works/v1alpha1
+ |
+||||||||
+kind+string + |
+
+GitOpsSet
+ |
+||||||||
+metadata+ + +Kubernetes meta/v1.ObjectMeta + + + |
+
+Refer to the Kubernetes API documentation for the fields of the
+metadata field.
+ |
+||||||||
+spec+ + +GitOpsSetSpec + + + |
+
+ + +
|
+||||||||
+status+ + +GitOpsSetStatus + + + |
++ | +
APIClientGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+APIClientGenerator defines a generator that queries an API endpoint and uses +that to generate data.
+| Field | +Description | +
|---|---|
+interval+ + +Kubernetes meta/v1.Duration + + + |
+
+ The interval at which to poll the API endpoint. + |
+
+endpoint+ +string + + |
+
+(Optional)
+ This is the API endpoint to use. + |
+
+method+ +string + + |
+
+ Method defines the HTTP method to use to talk to the endpoint. + |
+
+jsonPath+ +string + + |
+
+ JSONPath is string that is used to modify the result of the API +call. +This can be used to extract a repeating element from a response. +https://kubernetes.io/docs/reference/kubectl/jsonpath/ + |
+
+headersRef+ + +HeadersReference + + + |
+
+(Optional)
+ HeadersRef allows optional configuration of a Secret or ConfigMap to add +additional headers to an outgoing request. +For example, a Secret with a key Authorization: Bearer abc123 could be +used to configure an authorization header. + |
+
+body+ + +Kubernetes pkg/apis/apiextensions/v1.JSON + + + |
+
+(Optional)
+ Body is set as the body in a POST request. +If set, this will configure the Method to be POST automatically. + |
+
+singleElement+ +bool + + |
+
+(Optional)
+ SingleElement means generate a single element with the result of the API +call. +When true, the response must be a JSON object and will be returned as a +single element, i.e. only one element will be generated containing the +entire object. + |
+
+secretRef+ + +Kubernetes core/v1.LocalObjectReference + + + |
+
+ Reference to Secret in same namespace with a field “caFile” which +provides the Certificate Authority to trust when making API calls. + |
+
ClusterGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+ClusterGenerator defines a generator that queries the cluster API for +relevant clusters.
+| Field | +Description | +
|---|---|
+selector+ + +Kubernetes meta/v1.LabelSelector + + + |
+
+(Optional)
+ Selector is used to filter the clusters that you want to target. +If no selector is provided, no clusters will be matched. + |
+
ConfigGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+ConfigGenerator loads a referenced ConfigMap or +Secret from the Cluster and makes it available as a resource.
+| Field | +Description | +
|---|---|
+kind+ +string + + |
+
+ Kind of the referent. + |
+
+name+ +string + + |
+
+ Name of the referent. + |
+
GitOpsSetGenerator +
++(Appears on: +GitOpsSetSpec) +
+GitOpsSetGenerator is the top-level set of generators for this GitOpsSet.
+| Field | +Description | +
|---|---|
+list+ + +ListGenerator + + + |
++ | +
+pullRequests+ + +PullRequestGenerator + + + |
++ | +
+gitRepository+ + +GitRepositoryGenerator + + + |
++ | +
+ociRepository+ + +OCIRepositoryGenerator + + + |
++ | +
+matrix+ + +MatrixGenerator + + + |
++ | +
+cluster+ + +ClusterGenerator + + + |
++ | +
+apiClient+ + +APIClientGenerator + + + |
++ | +
+imagePolicy+ + +ImagePolicyGenerator + + + |
++ | +
+config+ + +ConfigGenerator + + + |
++ | +
GitOpsSetNestedGenerator +
++(Appears on: +MatrixGenerator) +
+GitOpsSetNestedGenerator describes the generators usable by the MatrixGenerator. +This is a subset of the generators allowed by the GitOpsSetGenerator because the CRD format doesn’t support recursive declarations.
+| Field | +Description | +
|---|---|
+name+ +string + + |
+
+(Optional)
+ Name is an optional field that will be used to prefix the values generated +by the nested generators, this allows multiple generators of the same +type in a single Matrix generator. + |
+
+list+ + +ListGenerator + + + |
++ | +
+gitRepository+ + +GitRepositoryGenerator + + + |
++ | +
+ociRepository+ + +OCIRepositoryGenerator + + + |
++ | +
+pullRequests+ + +PullRequestGenerator + + + |
++ | +
+cluster+ + +ClusterGenerator + + + |
++ | +
+apiClient+ + +APIClientGenerator + + + |
++ | +
+imagePolicy+ + +ImagePolicyGenerator + + + |
++ | +
+config+ + +ConfigGenerator + + + |
++ | +
GitOpsSetSpec +
++(Appears on: +GitOpsSet) +
+GitOpsSetSpec defines the desired state of GitOpsSet
+| Field | +Description | +
|---|---|
+suspend+ +bool + + |
+
+(Optional)
+ Suspend tells the controller to suspend the reconciliation of this +GitOpsSet. + |
+
+generators+ + +[]GitOpsSetGenerator + + + |
+
+ Generators generate the data to be inserted into the provided templates. + |
+
+templates+ + +[]GitOpsSetTemplate + + + |
+
+ Templates are a set of YAML templates that are rendered into resources +from the data supplied by the generators. + |
+
+serviceAccountName+ +string + + |
+
+(Optional)
+ The name of the Kubernetes service account to impersonate +when reconciling this Kustomization. + |
+
GitOpsSetStatus +
++(Appears on: +GitOpsSet) +
+GitOpsSetStatus defines the observed state of GitOpsSet
+| Field | +Description | +
|---|---|
+ReconcileRequestStatus+ + +github.com/fluxcd/pkg/apis/meta.ReconcileRequestStatus + + + |
+
+
+(Members of |
+
+observedGeneration+ +int64 + + |
+
+(Optional)
+ ObservedGeneration is the last observed generation of the HelmRepository +object. + |
+
+conditions+ + +[]Kubernetes meta/v1.Condition + + + |
+
+(Optional)
+ Conditions holds the conditions for the GitOpsSet + |
+
+inventory+ + +ResourceInventory + + + |
+
+(Optional)
+ Inventory contains the list of Kubernetes resource object references that +have been successfully applied + |
+
GitOpsSetTemplate +
++(Appears on: +GitOpsSetSpec) +
+GitOpsSetTemplate describes a resource to create
+| Field | +Description | +
|---|---|
+repeat+ +string + + |
+
+ Repeat is a JSONPath string defining that the template content should be +repeated for each of the matching elements in the JSONPath expression. +https://kubernetes.io/docs/reference/kubectl/jsonpath/ + |
+
+content+ + +k8s.io/apimachinery/pkg/runtime.RawExtension + + + |
+
+ Content is the YAML to be templated and generated. + |
+
GitRepositoryGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+GitRepositoryGenerator generates from files in a Flux GitRepository resource.
+| Field | +Description | +
|---|---|
+repositoryRef+ +string + + |
+
+ RepositoryRef is the name of a GitRepository resource to be generated from. + |
+
+files+ + +[]RepositoryGeneratorFileItem + + + |
+
+ Files is a set of rules for identifying files to be parsed. + |
+
+directories+ + +[]RepositoryGeneratorDirectoryItem + + + |
+
+ Directories is a set of rules for identifying directories to be +generated. + |
+
HeadersReference +
++(Appears on: +APIClientGenerator) +
+HeadersReference references either a Secret or ConfigMap to be used for +additional request headers.
+| Field | +Description | +
|---|---|
+kind+ +string + + |
+
+ The resource kind to get headers from. + |
+
+name+ +string + + |
+
+ Name of the resource in the same namespace to apply headers from. + |
+
ImagePolicyGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+ImagePolicyGenerator generates from the ImagePolicy.
+| Field | +Description | +
|---|---|
+policyRef+ +string + + |
+
+ PolicyRef is the name of a ImagePolicy resource to be generated from. + |
+
ListGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+ListGenerator generates from a hard-coded list.
+| Field | +Description | +
|---|---|
+elements+ + +[]Kubernetes pkg/apis/apiextensions/v1.JSON + + + |
++ | +
MatrixGenerator +
++(Appears on: +GitOpsSetGenerator) +
+MatrixGenerator defines a matrix that combines generators. +The matrix is a cartesian product of the generators.
+| Field | +Description | +
|---|---|
+generators+ + +[]GitOpsSetNestedGenerator + + + |
+
+ Generators is a list of generators to be combined. + |
+
+singleElement+ +bool + + |
+
+(Optional)
+ SingleElement means generate a single element with the result of the +merged generator elements. +When true, the matrix elements will be merged to a single element, with +whatever prefixes they have. +It’s recommended that you use the Name field to separate out elements. + |
+
OCIRepositoryGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+OCIRepositoryGenerator generates from files in a Flux OCIRepository resource.
+| Field | +Description | +
|---|---|
+repositoryRef+ +string + + |
+
+ RepositoryRef is the name of a OCIRepository resource to be generated from. + |
+
+files+ + +[]RepositoryGeneratorFileItem + + + |
+
+ Files is a set of rules for identifying files to be parsed. + |
+
+directories+ + +[]RepositoryGeneratorDirectoryItem + + + |
+
+ Directories is a set of rules for identifying directories to be +generated. + |
+
PullRequestGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+PullRequestGenerator defines a generator that queries a Git hosting service +for relevant PRs.
+| Field | +Description | +
|---|---|
+interval+ + +Kubernetes meta/v1.Duration + + + |
+
+ The interval at which to check for repository updates. + |
+
+driver+ +string + + |
+
+ Determines which git-api protocol to use. + |
+
+serverURL+ +string + + |
+
+(Optional)
+ This is the API endpoint to use. + |
+
+repo+ +string + + |
+
+ This should be the Repo you want to query. +e.g. my-org/my-repo + |
+
+secretRef+ + +Kubernetes core/v1.LocalObjectReference + + + |
+
+ Reference to Secret in same namespace with a field “password” which is an +auth token that can query the Git Provider API. + |
+
+labels+ +[]string + + |
+
+(Optional)
+ Labels is used to filter the PRs that you want to target. +This may be applied on the server. + |
+
+forks+ +bool + + |
+
+(Optional)
+ Fork is used to filter out forks from the target PRs if false, +or to include forks if true + |
+
RepositoryGeneratorDirectoryItem +
++(Appears on: +GitRepositoryGenerator, +OCIRepositoryGenerator) +
+RepositoryGeneratorDirectoryItem stores the information about a specific +directory to be generated from.
+| Field | +Description | +
|---|---|
+path+ +string + + |
++ | +
+exclude+ +bool + + |
++ | +
RepositoryGeneratorFileItem +
++(Appears on: +GitRepositoryGenerator, +OCIRepositoryGenerator) +
+RepositoryGeneratorFileItem defines a path to a file to be parsed when generating.
+| Field | +Description | +
|---|---|
+path+ +string + + |
+
+ Path is the name of a file to read and generate from can be JSON or YAML. + |
+
ResourceInventory +
++(Appears on: +GitOpsSetStatus) +
+ResourceInventory contains a list of Kubernetes resource object references that have been applied by a Kustomization.
+| Field | +Description | +
|---|---|
+entries+ + +[]ResourceRef + + + |
+
+ Entries of Kubernetes resource object references. + |
+
ResourceRef +
++(Appears on: +ResourceInventory) +
+ResourceRef contains the information necessary to locate a resource within a cluster.
+| Field | +Description | +
|---|---|
+id+ +string + + |
+
+ ID is the string representation of the Kubernetes resource object’s metadata, +in the format ‘namespace_name_group_kind’. + |
+
+v+ +string + + |
+
+ Version is the API version of the Kubernetes resource object’s kind. + |
+
+
diff --git a/userdocs/docs/gitopssets/gitopssets-api-reference.md b/userdocs/docs/gitopssets/gitopssets-api-reference.md
new file mode 100644
index 0000000000..211da5a6fa
--- /dev/null
+++ b/userdocs/docs/gitopssets/gitopssets-api-reference.md
@@ -0,0 +1,5 @@
+---
+title: API reference
+#template: _api.html
+---
+
diff --git a/userdocs/docs/gitopssets/gitopssets-installation.md b/userdocs/docs/gitopssets/gitopssets-installation.md
new file mode 100644
index 0000000000..85a54f5702
--- /dev/null
+++ b/userdocs/docs/gitopssets/gitopssets-installation.md
@@ -0,0 +1,81 @@
+---
+title: Installation
+
+---
+
+
+
+# Installation ~ENTERPRISE~
+
+The gitopssets-controller can be installed in two ways:
+
+- As part of the Weave GitOps Enterprise installation. (installed by default)
+- As a standalone installation using a Helm chart.
+
+The standalone installation can be useful for leaf clusters that don't have Weave GitOps Enterprise installed.
+
+## Prerequisites
+
+Before installing the gitopssets-controller, ensure that you've installed [Flux](https://github.com/fluxcd/flux2).
+
+## Installing the gitopssets-controller
+
+To install the gitopssets-controller using a Helm chart, use the following HelmRelease:
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+ name: gitopssets-system
+---
+apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: HelmRepository
+metadata:
+ name: weaveworks-oci-charts
+ namespace: gitopssets-system
+spec:
+ interval: 1m
+ type: oci
+ url: oci://ghcr.io/weaveworks/charts
+---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+ name: gitopssets-controller
+ namespace: gitopssets-system
+spec:
+ interval: 10m
+ chart:
+ spec:
+ chart: gitopssets-controller
+ sourceRef:
+ kind: HelmRepository
+ name: weaveworks-oci-charts
+ namespace: gitopssets-system
+ version: 0.15.3
+ install:
+ crds: CreateReplace
+ upgrade:
+ crds: CreateReplace
+```
+
+After adding the Namespace, HelmRepository and HelmRelease to a Git repository synced by Flux, commit the changes to complete the installation process.
+
+## Customising the Generators
+
+Not all generators are enabled by default, this is because not all CRDs are required by the generators.
+
+You might want to enable or disable individual generators via the Helm Chart:
+
+```yaml
+gitopssets-controller:
+ enabled: true
+ controllerManager:
+ manager:
+ args:
+ - --health-probe-bind-address=:8081
+ - --metrics-bind-address=127.0.0.1:8080
+ - --leader-elect
+ # enable the cluster generator which is not enabled by default
+ - --enabled-generators=GitRepository,Cluster,PullRequests,List,APIClient,Matrix,Config
+```
diff --git a/userdocs/docs/gitopssets/gitopssets-releases.md b/userdocs/docs/gitopssets/gitopssets-releases.md
new file mode 100644
index 0000000000..3935b37c7b
--- /dev/null
+++ b/userdocs/docs/gitopssets/gitopssets-releases.md
@@ -0,0 +1,125 @@
+---
+title: Releases
+
+---
+
+
+
+# Gitopssets Controller Releases ~ENTERPRISE~
+
+## v0.16.1
+2023-09-06
+
+- Bump client-go to 0.26.8 - avoids a buggy version of the upstream client
+ package
+
+## v0.16.0
+2023-09-05
+
+- Fix partial-apply resources bug - errors generating resources could lead to
+ incomplete inventories and errors when regenerating resources
+- Bump the memory limits for the Helm chart and document that these may need to
+ be increased.
+
+## v0.15.3
+2023-08-17
+
+- Fix bug when a Matrix generator doesn't generate any elements.
+
+## v0.15.2
+2023-08-17
+
+- Update the ImagePolicy generator to add the image by splitting the image from
+ the tag.
+
+## v0.15.1
+2023-08-17
+
+- Fix bug in the processing of empty artifacts in GitRepositories and
+ OCIRepositories - the directory listing will also return the special empty
+ marker when the Repository is empty.
+
+## v0.15.0
+2023-08-10
+
+- ClusterGenerator - return labels as generic maps - this makes it easier to
+ query for labels in a map.
+
+## v0.14.1
+2023-07-26
+
+- When a GitRepository or OCIRepository artifact is empty, handle this as a
+ special case that doesn't mean "no resources" this prevents removal of
+ resources when the Flux resource hasn't populated yet.
+
+## v0.14.0
+2023-07-14
+
+- Support multidoc when rendering via the CLI tool
+- Allow custom CAs for the APIGenerator HTTPClient
+- Single element Matrix generation - compress multiple Matrix elements into a
+ single element
+- Implement element index and repeat index
+- Local GitRepository generation from the filesystem in the CLI tool
+- Implement OCIGenerator - functionally very similar to the GitRepository
+ generator
+
+## v0.13.3
+2023-06-26
+
+- Secrets are now provided in Elements as strings rather than byte slices
+
+## v0.13.1
+2023-06-21
+
+- Expose the latest tag not just the latest image in the ImageRepository
+
+## v0.13.0
+2023-06-20
+
+- Fix bug in matrix generator when updating GitRepository resources
+- Config generator - track Secrets and ConfigMaps and generate from them
+- CLI tool for rendering GitOpsSets
+
+## v0.12.0
+2023-05-24
+
+- Allow altering the delimiters
+- Imagerepository generator by @bigkevmcd in #71
+- Allow cross-namespace resources
+- Upgrade the matrix to support "unlimited" numbers of generators
+- Add support for Flux annotation triggered rereconciliation
+
+## v0.11.0
+2023-05-10
+
+- Support for using the `repeat` mechanism within maps not just arrays
+
+## v0.10.0
+2023-04-28
+
+- Bump to support Flux v2
+
+## v0.9.0
+2023-04-27
+
+- Fail if we cannot find a relevant generator
+- Suppress caching of Secrets and ConfigMaps
+- Improve APIClient error message
+- Support correctly templating numbers - insertion of numeric values is improved
+
+## v0.8.0
+2023-04-13
+
+- Add events recording to GitOpsSets
+- Fix updating of ConfigMaps
+
+## v0.7.0
+2023-03-30
+
+- Implement custom delimiters
+
+## v0.6.1
+2023-03-20
+
+- Implement optional list expansion
\ No newline at end of file
diff --git a/userdocs/docs/gitopssets/index.md b/userdocs/docs/gitopssets/index.md
new file mode 100644
index 0000000000..e471d6daab
--- /dev/null
+++ b/userdocs/docs/gitopssets/index.md
@@ -0,0 +1,43 @@
+---
+title: Introduction
+
+---
+
+
+
+# GitOpsSets ~ENTERPRISE~
+
+!!! warning
+
+ **This feature is in alpha and certain aspects will change**
+
+ We're very excited for people to use this feature.
+ However, please note that some changes will be made to the API and behavior,
+ particularly to enhance security by implementing impersonation for more
+ fine-grained control over how the generated resources are applied.
+
+## Introduction
+
+GitOpsSets enable Platform Operators to have a single definition for an application for multiple environments and a fleet of clusters. A single definition can be used to generate the environment and cluster-specific configuration.
+
+As an example, we can take an application that needs to be deployed to various environments (Dev, Test, Prod) built by a fleet of clusters. Each of those environments + clusters requires a specialized configuration powering the same Application. With GitOpsSets and the generators you just declare the template you want to use, the selector that will match the cluster of the inventory, and where to get the special configuration.
+
+GitOpsSets will create out of the single resource all the objects and Flux primitives that are required to successfully deploy this application. An operation that required the editing of hundreds of files can now be done with a single command.
+
+**The initial generators that are coming with the preview release are:**
+
+- [List Generator](templating-from-generators.md#list-generator): The simplest generator. Provide a list of Key/Value pairs that you want to feed the template with.
+- [Git Generator](templating-from-generators.md#gitrepository-generator): Enables you to extract a set of files (environment-specific configurations) from a Flux GitRepository and make their contents available to the templates. This lets you have config in *app-dev.json*, *app-staging.json*, and *app-production.json*, for example.
+- [Matrix Generator](templating-from-generators.md#matrix-generator): Combine slices of generators into the desired compounded input.
+- [Pull request Generator](templating-from-generators.md#pullrequests-generator): Automatically discover open pull requests within a repository to generate a new deployment.
+- [API Client Generator](templating-from-generators.md#apiclient-generator): Poll an HTTP endpoint and parse the result as the generated values.
+- [OCI Repository](templating-from-generators.md#ocirepository-generator)
+- [Cluster](templating-from-generators.md#cluster-generator)
+- [ImagePolicy](templating-from-generators.md#imagepolicy-generator)
+- [Config](templating-from-generators.md#config-generator)
+
+## Use Cases
+
+- Single application definition for different environments (EU-West, North America, Germany)
+- Deployment of a single definition across fleet of clusters matching any cluster based on a label (Production)
+- Separation of concerns between teams (teams managing different artifacts flowing into a single definition via generators)
diff --git a/userdocs/docs/gitopssets/templating-from-generators.md b/userdocs/docs/gitopssets/templating-from-generators.md
new file mode 100644
index 0000000000..ae5b6eef91
--- /dev/null
+++ b/userdocs/docs/gitopssets/templating-from-generators.md
@@ -0,0 +1,1444 @@
+# Templating from Generators
+
+## Basics
+
+Currently rendering templates operates in two phases:
+
+- Generate all template parameters from the configured generators
+- Render all the templates for each set of template parameters
+
+Please read the [security information](#security) below before using this.
+
+## General behaviour
+
+GitOpsSets can be suspended, by setting the `spec.suspend` flag to be true.
+
+When this is the case, updates will not be applied, no resources created _or_
+deleted.
+
+In addition, a manual reconciliation can be requested by annotating a GitOpsSet
+with the `reconcile.fluxcd.io/requestedAt` annotation.
+
+## Generation
+
+The simplest generator is the `List` generator.
+
+```yaml
+apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: gitopsset-sample
+spec:
+ generators:
+ - list:
+ elements:
+ - env: dev
+ team: dev-team
+ - env: production
+ team: ops-team
+ - env: staging
+ team: ops-team
+```
+
+The elements in there are a set JSON of objects[^yaml], there are three in this example, and each of them has two keys, `env` and `team`.
+
+Other generators provide different sets of keys and values.
+
+The [generators](#generators) documentation below provides more information on what the other generators output.
+
+## Rendering templates
+
+Templates are Kubernetes resources in YAML format.
+
+Each template is rendered for each element generated by the generators.
+
+```yaml
+apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: gitopsset-sample
+spec:
+ generators:
+ - list:
+ elements:
+ - env: dev
+ team: dev-team
+ - env: production
+ team: ops-team
+ - env: staging
+ team: ops-team
+ templates:
+ - content:
+ kind: Kustomization
+ apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+ metadata:
+ name: "{{ .Element.env }}-demo"
+ labels:
+ app.kubernetes.io/name: go-demo
+ app.kubernetes.io/instance: "{{ .Element.env }}"
+ com.example/team: "{{ .Element.team }}"
+ spec:
+ interval: 5m
+ path: "./examples/kustomize/environments/{{ .Element.env }}"
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: go-demo-repo
+```
+
+The generated elements are provided to the template in the `Element` scope, so
+`.Element.dev` refers to the `dev` field from the List element.
+
+The output from all generators is exposed in the `Element` scope, not just List
+generators.
+
+In addition to the `.Element` field, a `.ElementIndex` is also available, this
+represents the zero-based index into the set of generated elements.
+
+**NOTE**: It's not recommended that you use this to name resources where the
+ordering of the queries for generating the elements is not guaranteed to be
+ordered, otherwise you could generate churn in resources as we look for
+resources by name when updating them, so, `.ElementIndex` 1 may not be the same
+as `.ElementIndex` 1 was the previous time, and this could cause resources to be
+updated unnecessarily with undesirable effects.
+
+## Repeating templates
+
+The output from a generator is an array of JSON objects[^yaml], the keys of which can contain repeating elements, either further JSON objects, or scalar values.
+
+It can be desirable to repeat a template for a repeated element in a generated
+value.
+
+```yaml
+apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: repeated-gitopsset-sample
+spec:
+ generators:
+ - list:
+ elements:
+ - env: dev
+ team: dev-team
+ teams:
+ - name: "team1"
+ - name: "team2"
+ - name: "team3"
+ - env: staging
+ team: staging-team
+ teams:
+ - name: "team4"
+ - name: "team5"
+ - name: "team6"
+ templates:
+ - repeat: "{ .teams }"
+ content:
+ kind: ConfigMap
+ apiVersion: v1
+ metadata:
+ name: "{{ .Repeat.name }}-demo"
+ data:
+ name: "{{ .Repeat.name }}-demo"
+ team: "{{ .Element.team }}"
+```
+
+The template `repeat` field is a [JSONPath](https://kubernetes.io/docs/reference/kubectl/jsonpath/) expression that is applied to each element during the template rendering.
+
+Templates that use `repeat` will have two separate scopes for the template params, `.Element` which is the top-level element generated by the generator, and the additional `.Repeat` scope, which is the repeating element.
+
+In this case, six different `ConfigMaps` are generated, three for the "dev-team" and three for the "staging-team".
+
+As with the `.ElementIndex`, for repeated elements both `.ElementIndex` **and** `.RepeatIndex` are available.
+
+## Delimiters
+
+The default delimiters for the template engine are `{{` and `}}`, which is the same as the Go template engine.
+
+These can be changed by adding an annotation to the `GitOpsSet`:
+
+```yaml
+apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: gitopsset-sample
+ annotations:
+ templates.weave.works/delimiters: "${{,}}"
+```
+
+Changing the delimiters can useful for:
+
+- Nesting GitopsSets within each other, as the default delimiters will conflict
+- Providing unquoted values to yaml
+
+### Unquoted values
+
+In yaml `{{` is invalid syntax and needs to be quoted. If you need to provide a un-quoted number value like `replicas: 3` you should use the `${{,}}` delimiters.
+
+- ❌ `replicas: {{ .params.REPLICAS }}` Invalid yaml
+- ❌ `replicas: "{{ .params.REPLICAS }}"` Valid yaml, incorrect type. The type is a string not a number and will fail validation.
+- ✅ `replicas: ${{ .params.REPLICAS }}` Valid yaml and correct number type.
+
+Unquoted values allow you to include objects in your templates too.
+
+```yaml
+apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: gitopsset-sample
+ annotations:
+ templates.weave.works/delimiters: "${{,}}"
+spec:
+ generators:
+ - list:
+ elements:
+ - env: dev
+ resources:
+ limits:
+ cpu: 100m
+ memory: 128Mi
+ - env: staging
+ resources:
+ limits:
+ cpu: 100m
+ memory: 128Mi
+ templates:
+ - content:
+ kind: Deployment
+ apiVersion: apps/v1
+ metadata:
+ name: go-demo
+ spec:
+ template:
+ spec:
+ containers:
+ - name: go-demo
+ image: weaveworks/go-demo:0.2.0
+ resources: ${{ .Element.resources | toJson }}
+```
+
+With the default `{{,}}` delimiters this would fail as the "resources" field would need to be quoted.
+
+Again, if we quote them we would get a string value, not an object.
+
+## Generators
+
+We currently provide these generators:
+- [list](#list-generator)
+- [pullRequests](#pullrequests-generator)
+- [gitRepository](#gitrepository-generator)
+- [ociRepository](#ocirepository-generator)
+- [matrix](#matrix-generator)
+- [apiClient](#apiclient-generator)
+- [cluster](#cluster-generator)
+- [imagepolicy](#imagepolicy-generator)
+- [config](#config-generator)
+
+### List generator
+
+This is the simplest generator, which is a hard-coded array of JSON objects, described as YAML mappings.
+
+### GitRepository generator
+
+The `GitRepository` generator operates on [Flux GitRepositories](https://fluxcd.io/flux/components/source/gitrepositories/).
+
+When a `GitRepository` is updated, this will trigger a regeneration of templates.
+
+The generator operates in two different ways, you can parse files (YAML or JSON) into Elements, or you can scan directories for subdirectories.
+
+#### Generation from files
+
+```yaml
+apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: repository-sample
+spec:
+ generators:
+ - gitRepository:
+ repositoryRef: go-demo-repo
+ files:
+ - path: examples/generation/dev.yaml
+ - path: examples/generation/production.yaml
+ - path: examples/generation/staging.yaml
+ templates:
+ - content:
+ kind: Kustomization
+ apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+ metadata:
+ name: "{{ .Element.env }}-demo"
+ labels:
+ app.kubernetes.io/name: go-demo
+ app.kubernetes.io/instance: "{{ .Element.env }}"
+ com.example/team: "{{ .Element.team }}"
+ spec:
+ interval: 5m
+ path: "./examples/kustomize/environments/{{ .Element.env }}"
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: go-demo-repo
+```
+
+In this example, a [Flux `GitRepository`](https://fluxcd.io/flux/components/source/gitrepositories/) called `go-demo-repo` in the same namespace as the `GitOpsSet` will be tracked, and `Kustomization` resources will be generated from the three files listed.
+
+These files can be JSON or YAML.
+
+In this example we expect to find the following structure in the files:
+
+```yaml
+env: dev
+team: developers
+```
+
+Changes pushed to the `GitRepository` will result in rereconciliation of the templates into the cluster.
+
+For security reasons, you need to explicitly list out the files that the generator should parse.
+
+#### Generation from directories
+
+```yaml
+apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ labels:
+ app.kubernetes.io/name: gitopsset
+ app.kubernetes.io/instance: gitopsset-sample
+ app.kubernetes.io/part-of: gitopssets-controller
+ app.kubernetes.io/managed-by: kustomize
+ app.kubernetes.io/created-by: gitopssets-controller
+ name: repository-sample
+spec:
+ generators:
+ - gitRepository:
+ repositoryRef: go-demo-repo
+ directories:
+ - path: examples/kustomize/environments/*
+ templates:
+ - content:
+ kind: Kustomization
+ apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+ metadata:
+ name: "{{ .Element.Base }}-demo"
+ labels:
+ app.kubernetes.io/name: go-demo
+ app.kubernetes.io/instance: "{{ .Element.Base }}"
+ com.example/team: "{{ .Element.Base }}"
+ spec:
+ interval: 5m
+ path: "{{ .Element.Directory }}"
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: go-demo-repo
+```
+
+In this example, a [Flux `GitRepository`](https://fluxcd.io/flux/components/source/gitrepositories/) called `go-demo-repo` in the same namespace as the `GitOpsSet` will be tracked, and `Kustomization` resources are generated from paths within the `examples/kustomize/environments/*` directory within the repository.
+
+Each generated element has two keys, `.Element.Directory` which will be a repo-relative path and `.Element.Base` which contains the last element of the path, for example, for a directory `./examples/kustomize/environments/production` this will be `production`.
+
+It is also possible to exclude paths from the generated list, for example, if you do not want to generate for a directory you can exclude it with:
+
+```yaml
+apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: repository-sample
+spec:
+ generators:
+ - gitRepository:
+ repositoryRef: go-demo-repo
+ directories:
+ - path: examples/kustomize/environments/*
+ - path: examples/kustomize/environments/production
+ exclude: true
+ templates:
+ - content:
+```
+
+In this case, all directories that are subdirectories of `examples/kustomize/environments` will be generated, **but** not `examples/kustomize/environments/production`.
+
+**Note**: The directory tree detection is restricted to the same directory as the path, no recursion is done.
+
+In fact the path is treated as a [Glob](https://pkg.go.dev/path/filepath#Glob).
+
+### OCIRepository generator
+
+The `OCIRepository` generator operates on [Flux OCIRepositories](https://fluxcd.io/flux/components/source/ocirepositories/).
+
+When an `OCIRepository` is updated, this will trigger a regeneration of templates.
+
+The `OCIRepository` generator operates in exactly the same way as the [GitRepository generator](#gitrepository-generator), except it operates on OCIRepositories.
+
+#### Generation from files
+
+```yaml
+apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: oci-repository-sample
+spec:
+ generators:
+ - ociRepository:
+ repositoryRef: go-demo-oci-repo
+ files:
+ - path: examples/generation/dev.yaml
+ - path: examples/generation/production.yaml
+ - path: examples/generation/staging.yaml
+ templates:
+ - content:
+ kind: Kustomization
+ apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+ metadata:
+ name: "{{ .Element.env }}-demo"
+ labels:
+ app.kubernetes.io/name: go-demo
+ app.kubernetes.io/instance: "{{ .Element.env }}"
+ com.example/team: "{{ .Element.team }}"
+ spec:
+ interval: 5m
+ path: "./examples/kustomize/environments/{{ .Element.env }}"
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: go-demo-repo
+```
+
+### PullRequests generator
+
+This will require to make authenticated requests to your Git hosting provider e.g. GitHub, GitLab, Bitbucket etc.
+
+It does only require read-only access, but all API tokens should be guarded as carefully as possible, what is a "read-only" token today, might become a token with higher-privilege in the future.
+
+_There have been many security compromises using API access tokens, do not let this happen to you!_
+
+```yaml
+apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: pull-requests-sample
+spec:
+ generators:
+ - pullRequests:
+ interval: 5m
+ driver: github
+ repo: bigkevmcd/go-demo
+ secretRef:
+ name: github-secret
+ templates:
+ - content:
+ apiVersion: source.toolkit.fluxcd.io/v1beta2
+ kind: GitRepository
+ metadata:
+ name: "pr-{{ .Element.Number }}-gitrepository"
+ namespace: default
+ spec:
+ interval: 5m0s
+ url: "{{ .Element.CloneURL }}"
+ ref:
+ branch: "{{ .Element.Branch }}"
+ - content:
+ apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+ kind: Kustomization
+ metadata:
+ name: "pr-{{ .Element.Number }}-demo"
+ namespace: default
+ spec:
+ interval: 5m
+ path: "./examples/kustomize/environments/dev"
+ prune: true
+ targetNamespace: "{{ .Element.Branch }}-ns"
+ sourceRef:
+ kind: GitRepository
+ name: "pr-{{ .Element.Number }}-gitrepository"
+```
+
+This example will poll "github.com/bigkevmcd/go-demo" for open pull requests and trigger the deployment of these by creating a Flux `GitRepository` and a `Kustomization` to deploy.
+
+As the generator only queries open pull requests, when a PR is closed, the generated resources will be removed.
+
+For non-public installations, you can configure the `serverURL` field and point it to your own installation.
+
+The `driver` field can be `github` or `gitlab` or `bitbucketserver`, other options can be supported from [go-scm](https://github.com/jenkins-x/go-scm/blob/main/scm/factory/factory.go).
+
+The `forks` flag field can be used to indicate whether to include forks in the target pull requests or not. If set to `true` any pull request from a fork repository will be included, otherwise if `false` or not indicated the pull requests from fork repositories are discarded.
+
+Additionally labels can be provided for querying pull requests with matching labels e.g.
+
+```yaml
+- pullRequests:
+ interval: 5m
+ driver: github
+ repo: bigkevmcd/go-demo
+ secretRef:
+ name: github-secret
+ forks: false
+ labels:
+ - deploy
+```
+
+The fields emitted by the pull-request are as follows:
+
+- `Number` this is generated as a string representation
+- `Branch` this is the source branch
+- `HeadSHA` this is the SHA of the commit in the merge branch
+- `CloneURL` this is the HTTPS clone URL for this repository
+- `CloneSSHURL` this is the SSH clone URL for this repository
+- `Fork` this indicates whether the pull request is from a fork (true) or not (false)
+
+Create a read-only token that can list Pull Requests, and store it in a secret:
+
+```shell
+$ kubectl create secret generic github-secret \
+ --from-literal password=This page was automatically generated with gen-crd-api-reference-docs
-
+
+pool:
+ vmImage: ubuntu-latest
+
+container:
+ image: weaveworks/weave-iac-validator:v1.1-azure
+
+steps:
+- script: weave-validator --path
- EntityFluxDeploymentsCard - shows a combined view of HelmReleases and Kustomizations
- EntityFluxSourcesCard - shows a combined view of GitRepositories, OCIRepositories and HelmRepositories
- EntityFluxHelmReleasesCard
- EntityFluxKustomizationsCard
- EntityFluxGitRepositoriesCard
- EntityFluxOCIRepositoriesCard
- EntityFluxHelmRepositoriesCard
AWSClusterStaticIdentity:AWSClusterAWSClusterRoleIdentity:AWSClusterAzureClusterIdentity:AzureClusterVSphereClusterIdentity:VSphereCluster-
the repository used to initially create the resource found in the
templates.weave.works/create-requestannotation (in the case of editing or deleting of resources)metadata: + annotations: + templates.weave.works/create-request: "{...\"parameter_values\":{...\"url\":\"https://github.com/weave-example-org/weave-demo\"}" + -
the first repository found with a
weave.works/repo-role: defaultannotationmetadata: + annotations: + weave.works/repo-role: default + -
the flux-system repository
metadata: + name: flux-system + namespace: flux-system + -
the first repository in the list of Git repositories that the user has access to.
github cli>= 2.3.0 (source)kubectl(source)eksctl(source)- the AWS Command Line Interface/
aws cli(source) clusterctl>= v1.1.3 (source); follow these steps to initialise the cluster and enable feature gatesclusterawsadm>= v1.1.0, following Cluster API's instructions- Make sure you have a management cluster. If you followed the Weave GitOps Enterprise installation guide, you'll have done this already.
- Configure your
AWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEYwith eitheraws configureor by exporting it in the current shell. - Set the
GITHUB_TOKENas an environment variable in the current shell. It should have permissions to create Pull Requests against the cluster config repo. - Select the clusters you want to delete
- Press the
Create a PR to delete clustersbutton - Either update the deletion PR values or leave the default values, depending on your situation
- Press the
Remove clustersbutton - Merge the PR for clusters deletion
- One path that shows you how to manage clusters without adding Cluster API. Join a cluster by hooking WGE to it, then install an application on that cluster.
- An optional path that shows you how to create, provision, and delete your first API cluster with EKS/CAPA.
- Create a new service account on the remote cluster:
- Add RBAC permissions for the service account:
- Retrieve the token from the service account. First, run this command to get the list of secrets of the service accounts:
- Create a kubeconfig secret. We'll use a helper script to generate the kubeconfig, and then save it into
static-kubeconfig.sh: -
Obtain the cluster certificate (CA). How you do this depends on your cluster.
-
AKS: Visit the Azure user docs for more information.
- EKS: Visit the EKS docs for more information.
- GKE: You can view the CA on the GCP Console: Cluster->Details->Endpoint->”Show cluster certificate”.
-
Update the following fields:
-
CLUSTER_NAME: insert the name of your cluster—i.e.,
demo-01 - ENDPOINT: add the API server endpoint i.e.
34.218.72.31 - CA_CERTIFICATE: include the path to the CA certificate file of the cluster
-
TOKEN: add the token of the service account retrieved in the previous step
-
Finally, create a secret for the generated kubeconfig in the WGE management cluster:
- Authentication strategies
- X509 client certificates: can be used across different namespaces
- Service account tokens: limited to a single namespace
- Kubernetes authentication 101 (CNCF blog post)
- Kubernetes authentication (Magalix blog post)
- Set up a WGE install environment.
- Collect artifacts and publish to a private registry.
- Install WGE in the air-gapped environment.
- Setup a proxy host
- Setup a private registry
- Install WGE
- docker as container runtime.
- kubectl and kind
- helm
- skopeo to manage container images
- flux to boostrap Flux in the environment.
- clusterctl to replicate the cluster management capabilities.
- Configure the environment variables to your context.
- Execute
maketo automatically sync Helm charts and container images. - Adjust Helm Releases
spec.chart.spec.sourceRefto tell Flux to pull Helm charts from your Helm repo. - Adjust Helm Releases
spec.valuesto use the container images from your private registry. - Configuration: flux-system
- Namespace: flux-system
- Scope: Cluster
apiopenidemailprofilehttps://localhost:8000/oauth/gitlabfor port-forwarding and testinghttps://git.example.com/oauth/gitlabfor production useGIT_HOST_TYPESto tell WGE that the host is gitlabGITLAB_HOSTNAMEwhere the OAuth app is hostedGIT_HOST_TYPESto tell WGE that the host is bitbucket-serverBITBUCKET_SERVER_HOSTNAMEwhere the OAuth app is hosted- Source Kind: Git repository
- Repository URL: [your repository URL here]
- Reference Type: Branch
- Repository Type: Private
- Authentication Source: Provide Authentication here
- SSH Key Authentication: Let the operator generate SSH Keys
- HTTPS User: YOUR_GITHUB_USERNAME
- HTTPS Key: YOUR_GITHUB_USER_PAT (Get one at this link. It's not the most secure method, but the easiest to get going.)
- Click Create
- Instance name: flux-system
- Path: clusters/default/demo3-azure-flux
- Prune: Ticked
- Day 0: you want to get started quickly for discovery with the less knowledge possible.
- Day 1: you have done discovery and want to set it up in your organisation.
- Interactive: guides you step-by-step through the process until Weave GitOps Enterprise is up and running.
- Non-interactive: for your automated workflows where you are already familiar with install process and have the configuration.
- Management Cluster: a Kubernetes cluster with a Kubeconfig that has Admin permissions to be able to create resources.
- Git Repository with SSH access: this is the configuration repo that WeaveGitOps will use to sync configuration manifests from.
- Flux CLI: is installed locally. It will be used for reconciling Flux resources.
- Flux Bootstrapped in your Management cluster via ssh. See Flux Bootstrap for more info.
- Weave GitOps Enterprise Entitlements are installed in the management cluster. Contact Sales for help on getting them.
- Verify Flux: verify Flux installation on the Management cluster.
- Verify Entitlement: verify the Entitlements secret content (username, password, entitlement).
- Configure Git Access: configure the access to your configuration repo.
- Select WGE version: from the latest 3 available releases.
- Create Cluster User: create a Secret with the username and password for the emergency cluster user.
- Configure Dashboard Access: choose between 2 methods to access the dashboard either local or external.
- Access the dashboard: via the link from the installation success message.
- (Optional) Configure OIDC: to enable login to dashboard via OIDC providers.
- Service: this option is called
localhostin the cli and the dashboard will be available through a ClusterIP Service. - Ingress: this option is called
externaldnsthe dashboard will be available through an Ingress with the following considerations:- An Ingress controller needs to exist.
- A host-based ingress will be created of the ingress class
public-nginx. - An ExternalDNS annotation will be added with the value of the provided domain.
--kube-config: allows to choose the Kubeconfig for your cluster, default would be ~/.kube/config-d,--domain externaldns: indicate the domain to use in case of using externaldns-t,--domain-type: dashboard domain type: could be 'localhost' or 'externaldns'-h,--help: help for bootstrap-p,--password: Dashboard admin password-k,--private-key: Private key path. This key will be used to push the Weave GitOps Enterprise's resources to the default cluster repository-c,--private-key-password: Private key password. If the private key is encrypted using password-u,--username: Dashboard admin username-v,--version: Weave GitOps Enterprise version to install- owner: The username (or organization) of the Git repository
- repository: Git repository name
- branch: Git branch (default "main")
- path: Path relative to the repository root; when specified, the cluster sync will be scoped to this path
- personal: If set, the owner is assumed to be a repo user
- components-extra: Additional controllers to install
wego-admin- Bound to the
ClusterRole, created by Helm,wego-admin-cluster-role - Aisha is the only member
wego-team-a-admin- Bound to a
Role, using the same permissions aswego-admin-role, created in Team-A's namespace - Brian and Aisha are members
wego-readonly- Bound to a
ClusterRolethat matcheswego-admin-cluster-rolebut with nopatchpermissions. - Aisha, Brian, June and Jo are all members
apiopenidemailprofilehttps://localhost:8000/oauth/gitlabfor port-forwarding and testinghttps://git.example.com/oauth/gitlabfor production useGIT_HOST_TYPESto tell WGE that the host is gitlabGITLAB_HOSTNAMEwhere the OAuth app is hostedGIT_HOST_TYPESto tell WGE that the host is bitbucket-serverBITBUCKET_SERVER_HOSTNAMEwhere the OAuth app is hostedvalues.policy-agent.enabled: set to true to install the agent with WGEvalues.policy-agent.config.accountId: organization name, used as identifiervalues.policy-agent.config.clusterId: unique identifier for the cluster- Cluster Management: We'll show you how to join WGE to a cluster and install an application on that cluster without using Cluster API. But if you prefer using Cluster API, our docs cover that too.
- Install the Terraform Controller to reconcile your Terraform resources in a GitOps way. With Flux and the TF Controller, WGE makes it easy to add Terraform templates to your clusters and continuously reconcile any changes made to the Terraform source manifest.
- Install Policy agent, which comes packaged with the WGE chart.
- Create a service account file:
- Create a roles file:
-
Commit to your fleet repo to sync.
-
Create a secret to store the kubeconfig, and a GitopsCluster object in the WGE management cluster that points to the kubeconfig secret. This allows you to connect to the target cluster and read various Kubernetes objects—including the Flux objects, such as:
- GitRepositories
- HelmReleases
- Kustomizations
- Providers
- Alerts
- Receivers
-
Add a new secret for the service account by adding to the service account yaml file in step 1.
-
Create a kubeconfig secret. We'll use a helper script to generate the kubeconfig, and then save it into
static-kubeconfig.sh:Expand to see script
static-kubeconfig.sh#!/bin/bash + +if [[ -z "$CLUSTER_NAME" ]]; then + echo "Ensure CLUSTER_NAME has been set" + exit 1 +fi + +if [[ -z "$CA_CERTIFICATE" ]]; then + echo "Ensure CA_CERTIFICATE has been set to the path of the CA certificate" + exit 1 +fi + +if [[ -z "$ENDPOINT" ]]; then + echo "Ensure ENDPOINT has been set" + exit 1 +fi + +if [[ -z "$TOKEN" ]]; then + echo "Ensure TOKEN has been set" + exit 1 +fi + +export CLUSTER_CA_CERTIFICATE=$(cat "$CA_CERTIFICATE" | base64) + +envsubst <<EOF +apiVersion: v1 +kind: Config +clusters: +- name: $CLUSTER_NAME + cluster: + server: https://$ENDPOINT + certificate-authority-data: $CLUSTER_CA_CERTIFICATE +users: +- name: $CLUSTER_NAME + user: + token: $TOKEN +contexts: +- name: $CLUSTER_NAME + context: + cluster: $CLUSTER_NAME + user: $CLUSTER_NAME +current-context: $CLUSTER_NAME + +EOF + -
Create a secret for the generated kubeconfig in the WGE management cluster:
kubectl create secret generic demo-01-kubeconfig \ +--from-file=value=./demo-01-kubeconfig + -
Create a GitopsCluster object. It must NOT be bootstrapped. Remove the annotation for bootstrap so it will not deploy Flux.
-
Commit to your fleet repo and sync.
-
Log in to your WGE management cluster to see if the cluster has appeared.
- ConnectCluster Functionality: Adding the foundation functionality to support connecting leaf clusters via CLI
gitops connect cluster. - Explorer extends source rendering to include OCIRepository resources to be rendered as regular flux sources.
- [UI Enhancement] Improved Top-Right Applied Status and Time Text for Applications and Terraform Details pages.
- flux >v2.0.0
- weave-gitops v0.31.2
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.1
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.5.0
- (optional) gitopssets-controller v0.15.3
- UI token refreshing! OIDC token refreshing is now handled by the UI, this avoids unintentionally making multiple token requests to the OIDC provider. This old behaviour sometimes triggered rate limiting in OIDC providers, causing errors.
- UI polish including removing duplicate error messages and more consistency in headers and font sizes.
- View Policy Audit violations in policies page as a tab
- ClusterGenerator - return labels as generic maps, allows for easily using them in params.
- Handle empty artifacts in directory processing, if a
GitRepositoryorOCIRepositoryhas no artifact, stop generating with an error. - Update the ImagePolicy generator to add the image.
- Ignore empty generators in the Matrix generator, fixing a panic if a generator produced an empty list.
- flux >v2.0.0
- weave-gitops v0.30.0
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.1
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.5.0
- (optional) gitopssets-controller v0.15.3
- flux >v2.0.0
- weave-gitops v0.29.0
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.3.0
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.5.0
- (optional) gitopssets-controller v0.14.1
- PR: #3126 - Uses weave-gitops v0.29.0 that as major changes include:
- Support for Flux v2.0.0
- Suspend/resume/reconcile Image Repositories
- Add Verified sources to Applications and Sources UI
- Using Flux v2.0.0 APIs. Managing
GitRepositoryv1,Kustomizationv1, andReceiverv1 resources. See Breaking Changes. - Generates metrics for indexer write operations
- flux >v2.0.0
- weave-gitops v0.29.0-rc.1
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.3.0
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.5.0
- (optional) gitopssets-controller v0.14.1
- PR: #3137 - Upgrade to Weave GitOps OSS v0.29.0-rc.1 and Flux v2.0.0 APIs
- PR: #3119 - Bump GitOpsSets to v0.14.0
- PR: #3134 - add RED metrics for indexer writes
- PR: #3098 - [UI] Cleanup forms across sections to ensure consistency
- PR: #3145 - Wge 3144 - create sops secrets uses v1 kustomizations api
- PR: #3146 - generate v1 kustomizations when adding apps
- PR: #3164 - Bump gitopssets-controller to v0.14.1
- PR: #3120 - Add large info display of Applied Revision and Last Updated on Terraform detail page
- PR: #3138 - Fix checkboxes on terraform data table
- This release drops the requirement to install cert-manager
- Extends external secrets creation form to allow selecting multiple properties or all properties
- Better support for organising your clusters and templates in the UI via namespaces
- Better support for Azure and Bitbucket Repositories in the UI, you can now click through to Open Pull Requests from these providers
- Dark Mode support for Policy Config
- Adds support for Kubernetes Events
- This version of Weave Gitops Enterprise drops support for
v1alpha1of theCAPITemplateandGitopsTemplateCRDs. Please migrate tov1alpha2of these CRDs. See the migration guide - weave-gitops v0.28.0
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.3.0
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.5.0
- (optional) gitopssets-controller v0.13.4
- Retries to make sure we're showing you the freshest data
- Exports more metrics to enhance observability
- Config generator enabled by default! Include values from ConfigMaps and Secrets in your GitOpsSets
- Dark mode enhancements
- Consistent form styling
- weave-gitops v0.26.0
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.2.0
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.5.0
- (optional) gitopssets-controller v0.13.4
- Dark Mode is now available in WGE.
- Added Prometheus metrics for all API endpoints.
- weave-gitops v0.26.0
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.2.0
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.5.0
- (optional) gitopssets-controller v0.13.2
- weave-gitops v0.25.1-rc.1
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.2.0
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.4.0
- (optional) gitopssets-controller v0.12.0
- GitOpsSets can now generate from Flux Image Automation's
ImagePolicy. This allows you to include the latest version of an image in your templates, for example to keep aDeploymentup to date. - Cross namespace support lands, create resources in multiple namespaces, they'll also be cleaned up properly via finalizers.
- The Sync button in the UI now works correctly
- You can now filter out the versions that will be shown from a HelmRepository when installing a chart via annotations:
"weave.works/helm-version-filter": "> 0.0.0"to filter out rc releases"weave.works/helm-version-filter": "> 1.0.0"to filter any pre 1.0 releases"weave.works/helm-version-filter": "> 3.0.0-0"to filter any pre 3.0 releases but include rc releases- You could now navigate by filters and enabled full-text search.
- Full-text search with terms including special characters like dashes (-) returns more results than expected by exact match term. For example, searching by term "flux-system" is treated as two terms: "flux" & "system" so returns the results for the joint of them. A fix for this will be part of the following releases.
- weave-gitops v0.24.0
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.2.0
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.3.0
- (optional) gitopssets-controller v0.12.0
- Health status is now displayed for Kubernetes built-in resources.
- You could configure the service account to use for collecting resources.
- You can now provide a Markdown description of a template. This will be rendered at the top of the Template page allowing template authors to provide clear instructions to their users on how to best fill in the values and complete any other required tests and checks.
- Raw templates are more flexible and allow you to render resources which don't have an explicit
metadata.namefield. - The cluster details page now shows a Cluster's Connectivity status, along with more details for both GitopsClusters and CAPIClusters, including:
- Conditions
- Labels
- Annotations
- When enabled useQueryServiceBackend navigation from Clusters UI to Applications UI is not possible as Explorer does not yet support filtering.
- weave-gitops v0.23.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.2.0
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.3.0
- (optional) gitopssets-controller v0.11.0
- Explorer supports now Flux sources.
- Applications UI and Sources UI could be configured to use Explorer backend to improve UI experience.
- Explorer collector uses impersonation. Ensure you configure collector for your leaf clusters.
- Now supports correctly templating numbers and object chunks
- Don't wait for ControlPlane readiness to sync secrets, this allows secrets to be sync'd related to CNI or other early stage processes
- Explorer: you should configure collector service account in your leaf clusters.
- Clusters page horizontally scrolls too much and status becomes unreadable for some fields
- weave-gitops v0.22.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.2.0
- (optional) pipeline-controller v0.20.0
- (optional) policy-agent v2.3.0
- (optional) gitopssets-controller v0.9.0
- See your gitopssets on leaf clusters in the UI
- Fixed bug where gitopssets would not update ConfigMaps
- View Open Pull requests button in the UI now allows you to select any GitRepository
- weave-gitops v0.21.2
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.5.0
- templates-controller v0.1.4
- (optional) pipeline-controller v0.20.0
- (optional) policy-agent v2.3.0
- (optional) gitopssets-controller v0.8.0
- weave-gitops v0.20.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.5.0
- templates-controller v0.1.4
- (optional) pipeline-controller v0.20.0
- (optional) policy-agent v2.3.0
- (optional) gitopssets-controller v0.7.0
- Gitopsssets come to the UI!
- weave-gitops v0.19.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- templates-controller v0.1.4
- (optional) pipeline-controller v0.20.0
- (optional) policy-agent v2.3.0
- (optional) gitopssets-controller v0.6.0
- See the logged in user's OIDC groups in the UI via the new User Profile page
- Image Automation pages now show cluster information
- See details about the configured promotion strategy for a pipeline
- Log filtering by source and level for GitOps Run
- See all Policy Configs listed in the UI
- New
clustergenerator allows you to interact with the Weave GitOps Cluster inventory. GitOps Clusters that are added and removed to the inventory are reflected by the generator. That can be used to target for example to manage applications across a fleet of clusters. - Enhanced
gitRepositorygenerator can now scan directories and paths with the newdirectoryoption, which enables you to create for example dynamically Flux Kustomizations , based on your repository. - New
apiClientgenerator allows you to query and endpoint, and provide data for your template. - Reconciliation metrics are now reported to the
/metricsendpoint ready to be collected - weave-gitops v0.18.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- templates-controller v0.1.3
- (optional) pipeline-controller v0.20.0
- (optional) policy-agent v2.3.0
- (optional) gitopssets-controller v0.5.0
- It's becoming easier to create new a external secret CR through the UI instead of writing the whole CR yaml.
- The creation form will help users choose which cluster to deploy the External Secret to and which secret store to sync the secrets from.
- It's all done in the GitOps way.
- Adding Add Plan button in the terraform plan page to enable users to re-plan changes made.
- weave-gitops v0.16.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- templates-controller v0.1.2
- (optional) pipeline-controller v0.14.0
- (optional) policy-agent v2.2.0
- (optional) gitopssets-controller v0.2.0
- Weave GitOps Enterprise, is now supporting via the WGE GUI the selection of the Git Repository. Enabling to scale and match the desired Git Repository structure.
- Supporting path for Profiles, enabling to set the path for profiles in the template to configure where in the directory the HelmRelease gets created.
- Enhanced Enterprise CLI support for GitOps Templates.
- Support for profiles in templates via CLI
gitops create templatesupporting--configallows you to read command line flags from a config file and--output-dirallows you to write files out to a directory instead of just stdout- GitOpsSets enable Platform Operators to have a single definition for an application for multiple environments and a fleet of clusters. A single definition can be used to generate the environment and cluster-specific configuration.
- GitOpsSets has been released as a feature in preview of WGE. The Preview phase helps us to actively collect feedback and use cases, iterating and improving the feature to reach a level of maturity before we call it stable. Please contact us via email or slack if you want to get access to the preview.
- Allows customising the requested scopes via config.oidc.customScopes: "email,groups,something_else"
- Token refreshing is now supported
- weave-gitops v0.15.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- (optional) pipeline-controller v0.9.0
- (optional) policy-agent v2.2.0
- We are introducing new functionality into Weave GitOps Enterprise to help observe and manage secrets through external secrets operator (ESO). The new secrets UI will enable customers using ESO to observe and manage external secrets, as well as help them troubleshoot issues during their secrets creation and sync operations. In this release, we are including the ability to list all ExternalSecrets custom resources across multi-cluster environments. Users also will have the ability to navigate to each ExternalSecret and know the details of the secret, its sync status, and the last time this secret has been updated, as well as the latest events associated with the secret.
- Retry promotion on failure. Now if a promotion fails there is an automatic retry functionalty, you can configure the threshold and delay via the CLI.
- Promotion webhook rate limiting. We enable now the configuration of the rate limit for the promotion webhooks.
- weave-gitops v0.14.1
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- (optional) pipeline-controller v0.9.0
- (optional) policy-agent v2.2.0
- GitOps templates now provide the capability to write resources to multiple paths in the Git repository. This feature allows complex scenarios, like for example creating a self-service for an application that requires an RDS database. We’ve provided documentation which has a example.
- Weave GitOps now provides a GUI for Workspaces.
- Weave GitOps now provides more details on the Terraform inventory GUI page. Adding the type and identifier fields to the inventory table, plus filtering and a 'no data' message.
- Weave GitOps now building and printing a list of set up port forwards.
- Weave GitOps now opening the selected port forward URL on key press. Listening for keypress is performed with the
github.com/mattn/go-ttypackage (other options required pressing Enter after a keypress, this catches just a single numeric keypress) and opening URLs with thegithub.com/pkg/browserpackage. - weave-gitops v0.13.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- (optional) pipeline-controller v0.8.0
- (optional) policy-agent v2.2.0
- Support to specify Helm charts inside the CRD, instead of annotations. We’ve provided documentation which has a example.
- Ability to edit all fields now, including name/namespace
- Support Azure DevOps and auto-remediation in commit-time enforcement.
- Weave GitOps default admin user can now “read” all objects. Why is this important? As users are trying out Weave GitOps they will most likely try it out with some of their favorite Cloud Native tools such as Crossplane, Tekton, Istio, etc. This enables them to see all of those resources and explore the full power of Weave GitOps. We still do not recommend this user for “production-use” cases, and customers should always be pushed towards implementing OIDC with scoped roles.
- From the Pipelines view you can add new Pipelines in a way which leverages GitOpsTemplates, additionally - to help users configure these, we’ve provided documentation which has some samples.
- Support for running multiple flux instances in different namespaces on a single cluster for resource isolation.
- [UI] Notifications provider page shows a 404.
- We are working towards unifying CAPI and GitOps Templates under a single umbrella. For those already using CAPITemplates, we will ensure a smooth transition is possible by making use of a conversion hooks. There are some breaking changes for GitOpsTemplates as part of this transitionary period, so be sure to check the guidance under Breaking Changes.
- We now retain the ordering of parameters in the template instead of sorting them alphabetically. Providing to the author control in what sequence the parameters are rendered in the form and thus present a more logically grouped set of parameters to the end consumer.
- You can control what delimiters you want to use in a template. This provides flexibility for if you want to use the syntax for dynamic functions like the helper functions we support.
- This feature is now enabled by default when you install the Weave GitOps Enterprise Helm Chart. You can toggle this with the
enablePipelinesflag. - GitOpsTemplates are a highly flexible way to create new resources - including Pipelines. We now provide a shortcut on the Pipelines table view to navigate you to Templates with the
weave.works/template-type=pipelinelabel. - weave-gitops v0.11.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- (optional) pipeline-controller v0.0.11
- (optional) policy-agent 2.1.1
- Retain template parameter ordering.
- Allow configuration of the delimiters in templates.
- Add create a pipeline button.
- add missing support for policy version v2beta2 to tenancy cmd.
- weave-gitops v0.10.2
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- (optional) policy-agent 2.1.1
- Create non-cluster resources / Add Edit option to resources with create-request annotation
- bump pipeline-controller
- Parse annotations from template
- Add cost estimate message if available
-
Adds support for showing policy modes and policy configs in the UI
-
Show suspended status on pipelines detail
- YAML view for Pipelines
-
Align and link logo
-
Actually remove the watcher from the helm-watcher-cache
-
UI 1817 disable create target name space if name space is flux system
-
Adding edit capi cluster resource acceptance test
- Add preview acceptance test
- weave-gitops v0.10.1
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- (optional) policy-agent 2.0.0
- When adding applications, you can now preview the changes(PR) before creating a pull request
- You can now see included Cluster Profiles when previewing your Create Cluster PR
- Notifications are now available in the Notifications Page
- You can now automatically create namespace when adding applications
- weave-gitops v0.9.6
- cluster-controller v1.3.2
- cluster-bootstrap-controller v0.3.0
- (optional) policy-agent 1.2.1
- Tenancy
gitops create tenantnow supports--pruneto remove old resources from the cluster if you're not using--exportwith GitOps.deploymentRBACsection intenancy.yamlallows you to specify the permissions given to the fluxKustomizationsthat will apply the resources from git to your tenants' namespaces in the cluster.- Support for
OCIRepositorysources when restricting/allowing the sources that can be applied into tenants' namespaces. - Templates
- Templates now support helm functions for simple transformations of values:
{{ .params.CLUSTER_NAME | upper }} - Templates has moved to its own page in the UI, this is the first step in moving towards embracing them as a more generic feature, not just for cluster creation.
- If a version is not specified in a template profile annotation it can be selected by the user.
- A
namespacecan be specified in the template profile annotation that will be provided as theHelmRelease'stargetNamespaceby default. - Bootstrapping
- A ClusterBootstrapConfig can now optionally be triggered when
phase="Provisioned", rather thanControlPlaneReady=Truestatus. - weave-gitops v0.9.5
- cluster-controller v1.3.2
- cluster-bootstrap-controller v0.3.0
- (optional) policy-agent 1.1.0
- [UI] Notifications page shows a 404 instead of the notification-controller's configuration.
.spec.values.enableExplorer: feature flag to control whether Explorer is enabled..spec.values.useQueryServiceBackend: feature flag to control whether you want to leverage Explorer backend capabilities for other UI experiences like Applications or Sources.spec.values.explorer.collector.serviceAccount: ServiceAccountnameandnamespacethat explorer collector will use to impersonate in leaf clusters. Make sure you read authz for collector before setting it. Default values arename: collector,namespace: flux-system.- HelmRelease
- Kustomizations
- Sources
- GitRepostiories
- OciRepositories
- HelmRepositories
- HelmCharts
- Buckets
- The read or querying path is exercised when a weave gitops user queries the data.
- The write or collecting path is exercised to gather the resources from the leaf clusters.
- Create a ServiceAccount for the one that you specified in your setup
.spec.values.explorer.collector.serviceAccount. - Create a ClusterRole with the permissions to watch the supported resources.
- Create a ClusterRolebinding to assign previous ClusterRole to the created collector
ServiceAccount. - Extend impersonation rules to allow service account impersonation for ServiceAccount
collector - See querying to deep dive in how to query.
- See operations for day troubleshooting and operations.
- You have Weave Gitops Enterprise v0.23.0 or later version
- You have deployed an application.
- A search dialog with filter to querying the platform resources
- A table with the filtered resources.
- API server
- Datastore Reads
- Indexer Reads
actionis the datastore read operation that could be eitherGetObjects,GetAccessRules,GetObjectByID,GetRolesorGetRoleBindings.statusis the result of the operation. It could be either read operation that could be eithersuccessorerror.actionis the datastore read operation that could be eitherGetObjects,GetAccessRules,GetObjectByID,GetRolesorGetRoleBindingsactionis the index read operation that could be eitherListFacetsorSearchstatusis the result of the operation. It could be either read operation that could be eithersuccessorerroractionis the index read operation that could be eitherListFacetsorSearch- Cluster Watcher Manager
- Datastore Writes
- Indexer Writes
actionis the datastore write operation that could be eitherStoreRoles,StoreRoleBindings,StoreObjects,DeleteObjects,DeleteAllObjects,DeleteRoles,DeleteAllRoles,DeleteRoleBindings,DeleteAllRoleBindingsstatusis the result of the operation. It could be either read operation that could be eithersuccessorerroractionis the datastore write operation that could be eitherStoreRoles,StoreRoleBindings,StoreObjects,DeleteObjects,DeleteAllObjects,DeleteRoles,DeleteAllRoles,DeleteRoleBindings,DeleteAllRoleBindingsactionis the index write operation that could be eitherAdd,RemoveorRemoveByQuerystatusis the result of the operation. It could be eithersuccessorerroractionis the index write operation that could be eitherAdd,RemoveorRemoveByQuery- Raise an issue
- Invite yourself to the Weave Users Slack.
- Chat to us on the #weave-gitops slack channel.
- Set up time with one of our team: James - Product Director (US - East Coast)
- Come along to one of our events
- The specific sub command itself - e.g.
gitops get bcrypt-hash - The name of the flags used, without the value (e.g.
--password, but not the value) - A random string used as an anonymous user ID, stored on your machine
-
- Note: We have no way of tracking individual users. We can only distinguish between user counts and event counts
- Whether the user has installed the Enterprise or open-source version of the CLI
- A value of
app=cli, to know it’s a CLI metric - Your browser, version, and user agent
- The domain name of your server
- Every page interaction, and the time each page is left open
- All button interactions
- The complete URL of every page, including which resource you look at, and searches done
- We can push new content into your browser, to add questions, guides, or more data points
- We send a unique user hash, based on your user name
-
- Note: We are not able to cross-reference unique users between here and anywhere else - not even your command line - but it gives us the ability to distinguish between user counts and event counts.
- Finally, we include a persistent ID representing your cluster, based on a hash of your
kube-systemnamespace uuid -
- Note: There is no way for us to track individual clusters using this, but it gives us the ability to distinguish between cluster counts and event counts.
- In CI/CD systems where you want to render a template and then use the raw output in a pipeline
- For quickly debugging templates
application- for application templatescluster- for cluster templatesterraform- for Terraform templatespipeline- for Pipeline templatesprofileskustomizationscredentials- Applications:
HelmReleaseKustomization- Sources:
HelmRepositoryGitRepository- Clusters:
GitopsClustername: The variable name within the resource templates.description: Description of the parameter. This will be rendered in both the UI and CLI.options: The list of possible values this parameter can be set to.required- Whether the parameter must contain a non-empty value.default- Default value of the parameter.name- is the name of the profile in the default profiles repositoryversion- (optional) will choose the default versionnamespace- (optional) is the default target namespace for the profileeditable- (optional, default=false), allow the user to de-select this profile, making it a default instead of a requirement.pipeline-view: A template to create a sample pipeline to visualize aHelmReleaseapplication delivered to dev, test and prod environments.pipeline-promotion-resources: A template to create the Flux Notification Controller resources required for promoting applications via pipelines.pipeline-view-promote-by-cluster: A template to create pipelines for hard tenancy when applications are isolated by cluster.pipeline-view-promote-by-namespace: A template to create pipelines for soft tenancy when applications are isolated by namespace.- The path is relative to the repository root
- The path can be templated using params
- The
rawkey is not compatible with thecontentkey. Only one of the two can be used. - The
rawkey data must still be a valid kubernetes unstructured object. templates.weave.works/delimiters: "{{,}}"- defaulttemplates.weave.works/delimiters: "${{,}}"- Use
${{and}}, for example"${{ .params.CLUSTER_NAME }}" - Useful as
{{in yaml is invalid syntax and needs to be quoted. If you need to provide a un-quoted number value likereplicas: 3you should use these delimiters. -
replicas: {{ .params.REPLICAS }}Invalid yaml - replicas: "{{ .params.REPLICAS }}"Valid yaml, incorrect type. The type is astringnot anumberand will fail validation. -
replicas: ${{ .params.REPLICAS }}Valid yaml and correctnumbertype. templates.weave.works/delimiters: "<<,>>"- Use
<<and>>, for example<< .params.CLUSTER_NAME >> - Useful if you are nesting templates and need to differentiate between the delimiters used in the inner and outer templates.
- +GitOpsSet +
- As part of the Weave GitOps Enterprise installation. (installed by default)
- As a standalone installation using a Helm chart.
- Bump client-go to 0.26.8 - avoids a buggy version of the upstream client package
- Fix partial-apply resources bug - errors generating resources could lead to incomplete inventories and errors when regenerating resources
- Bump the memory limits for the Helm chart and document that these may need to be increased.
- Fix bug when a Matrix generator doesn't generate any elements.
- Update the ImagePolicy generator to add the image by splitting the image from the tag.
- Fix bug in the processing of empty artifacts in GitRepositories and OCIRepositories - the directory listing will also return the special empty marker when the Repository is empty.
- ClusterGenerator - return labels as generic maps - this makes it easier to query for labels in a map.
- When a GitRepository or OCIRepository artifact is empty, handle this as a special case that doesn't mean "no resources" this prevents removal of resources when the Flux resource hasn't populated yet.
- Support multidoc when rendering via the CLI tool
- Allow custom CAs for the APIGenerator HTTPClient
- Single element Matrix generation - compress multiple Matrix elements into a single element
- Implement element index and repeat index
- Local GitRepository generation from the filesystem in the CLI tool
- Implement OCIGenerator - functionally very similar to the GitRepository generator
- Secrets are now provided in Elements as strings rather than byte slices
- Expose the latest tag not just the latest image in the ImageRepository
- Fix bug in matrix generator when updating GitRepository resources
- Config generator - track Secrets and ConfigMaps and generate from them
- CLI tool for rendering GitOpsSets
- Allow altering the delimiters
- Imagerepository generator by @bigkevmcd in #71
- Allow cross-namespace resources
- Upgrade the matrix to support "unlimited" numbers of generators
- Add support for Flux annotation triggered rereconciliation
- Support for using the
repeatmechanism within maps not just arrays - Bump to support Flux v2
- Fail if we cannot find a relevant generator
- Suppress caching of Secrets and ConfigMaps
- Improve APIClient error message
- Support correctly templating numbers - insertion of numeric values is improved
- Add events recording to GitOpsSets
- Fix updating of ConfigMaps
- Implement custom delimiters
- Implement optional list expansion
- List Generator: The simplest generator. Provide a list of Key/Value pairs that you want to feed the template with.
- Git Generator: Enables you to extract a set of files (environment-specific configurations) from a Flux GitRepository and make their contents available to the templates. This lets you have config in app-dev.json, app-staging.json, and app-production.json, for example.
- Matrix Generator: Combine slices of generators into the desired compounded input.
- Pull request Generator: Automatically discover open pull requests within a repository to generate a new deployment.
- API Client Generator: Poll an HTTP endpoint and parse the result as the generated values.
- OCI Repository
- Cluster
- ImagePolicy
- Config
- Single application definition for different environments (EU-West, North America, Germany)
- Deployment of a single definition across fleet of clusters matching any cluster based on a label (Production)
- Separation of concerns between teams (teams managing different artifacts flowing into a single definition via generators)
- Generate all template parameters from the configured generators
- Render all the templates for each set of template parameters
- Nesting GitopsSets within each other, as the default delimiters will conflict
- Providing unquoted values to yaml
- ❌
replicas: {{ .params.REPLICAS }}Invalid yaml - ❌
replicas: "{{ .params.REPLICAS }}"Valid yaml, incorrect type. The type is a string not a number and will fail validation. - ✅
replicas: ${{ .params.REPLICAS }}Valid yaml and correct number type. Numberthis is generated as a string representationBranchthis is the source branchHeadSHAthis is the SHA of the commit in the merge branchCloneURLthis is the HTTPS clone URL for this repositoryCloneSSHURLthis is the SSH clone URL for this repositoryForkthis indicates whether the pull request is from a fork (true) or not (false)ClusterNamethe name of the clusterClusterNamespacethe namespace that this cluster is fromClusterLabelsthe labels from the metadata field on the GitOpsClusterClusterAnnotationsthe annotations from the metadata field on the GitOpsCluster- latestImage - the latest image from the status field on the
ImagePolicy - latestTag - only the tag part of the latestImage, e.g. will be v0.1 for an image of "testing/image:v0.1"
- previousImage - the previous image from the status field on the
ImagePolicy - sanitize - sanitises strings to be compatible with Kubernetes DNS name requirements
- getordefault - gets a key from the
.Elementor defaults to another value. - The annotation key must start with the domain
metadata.weave.works. Any other annotations will be ignored. - The key that will be displayed is whatever you put after the domain, title cased, and with dashes replaced with spaces. Above,
metadata.weave.works/grafana-dashboardwas displayed as "Grafana Dashboard". - The value can either be a link, or can be plain text. Newlines in plain text will be respected.
- The key is subject to certain limitations that kubernetes imposes on annotations, including:
- it must be shorter than 63 characters (not including the domain)
- it must be an English alphanumeric character, or one of
-._. - See the kubernetes documentation for the full list of restrictions.
Flux Beta or Flux v0.xas the latest Flux Beta Release.Flux GAas the latest Flux GA Release CandidateWeave GitOpsas the latest Weave GitOps Enterprise release- EKS Anywhere
- Azure AKS Flux-GitOps extension
- Upgrade to Flux GA on your existing leaf clusters and management clusters
- Upgrade to Flux GA in
ClusterBootstrapConfigs. - Upgrade to latest Weave GitOps.
- Upgrade GitopsTemplates, GitopsSets and ClusterBootstrapConfigs.
- GitOps for absolute beginners - eBook from Weaveworks
- Guide to GitOps - from Weaveworks
- Awesome GitOps - inspired by https://github.com/sindresorhus/awesome
- Flux docs - comprehensive documentation on Flux
- OpenGitOps - CNCF Sandbox project aiming to define a vendor-neutral, principle-led meaning of GitOps.
- gitops.tech - supported by Innoq
mkdocs new [dir-name]- Create a new project.mkdocs serve- Start the live-reloading docs server.mkdocs build- Build the documentation site.mkdocs -h- Print help message and exit.
Continuous Delivery through GitOps for apps and infrastructure.
Support for GitHub, GitLab, and Bitbucket; S3-compatible buckets as a source; all major container registries; and all CI workflow providers.
A secure, pull-based mechanism, operating with least amount of privileges, and adhering to Kubernetes security policies.
Compatibility with any conformant Kubernetes version and common ecosystem technologies such as Helm, Kustomize, RBAC, Prometheus, OPA, Kyverno, etc.
Multitenancy, multiple Git repositories, multiple clusters.
Alerts and notifications.
Application Operations—manage and automate deployment pipelines for apps and more.
Easily have your own custom PaaS on cloud or on premise.
Coordinate Kubernetes rollouts with virtual machines, databases, and cloud services.
Drill down into more detailed information on any given Flux resource.
Uncover relationships between resources and quickly navigate between them.
Understand how workloads are reconciled through a directional graph.
View Kubernetes events relating to a given object to understand issues and changes.
Secure access to the dashboard through the ability to integrate with an OIDC provider (such as Dex).- Enable the monitoring server with the metrics endpoint.
- Install Kube Prometheus Stack.
- Deploy Weave GitOps Monitoring Config
- See the dashboards in Grafana. You can filter by tags
fluxorweave-gitops. - Enable the monitoring server with the profiling endpoint.
- Navigate to your monitoring server URL to the
/debug/pprofpath where the pprof web interface is exposed. - Clone or navigate back to your Git repository where you have bootstrapped Flux. For example:
- Create a
GitRepositorySource for podinfo. This will allow you to use different authentication methods for different repositories. - Commit and push the
podinfo-sourceto yourfleet-infrarepository - Create a
kustomizationto build and apply the podinfo manifest - Commit and push the
podinfo-kustomizationto yourfleet-infrarepository - Add the
patchessection as shown below to the field spec of yourpodinfo-kustomization.yamlfile so it looks like this: - Commit and push the
podinfo-kustomization.yamlchanges: - Navigate back to the dashboard. You should see a newly created pod:
- An account with a Git provider like GitHub or GitLab, along with a personal access token with repo permissions; if you're using GitHub, for example, go here
- Your Git client configured properly (if using GitHub, for example, then review their docs on setting your username and your email address)
- Docker Desktop
- A Kubernetes cluster such as Kind
- kubectl
- A public GitHub repo called
fleet-infra. To create this, follow GitHub’s instructions—usingfleet-infrainstead ofhello-world. - Add Flux component manifests to the repository
- Deploy Flux components to your Kubernetes cluster
- Configure the Flux components to track the path
./clusters/my-cluster/in the repository - use the GitOps CLI tool to generate
HelmReleaseandHelmRepositoryobjects. - create some login credentials to access the dashboard. This is a simple but insecure method of protecting and accessing your GitOps dashboard.
- commit the generated yamls to our
fleet-infrarepo. - observe that they are synced to the cluster.
- If you are running the UI on a subpath, you need to set the
pathfield to the same subpath specified in the--route-prefixflag. - If you have not set a subpath on the weave-gitops server, set the path in the ingress configration to
/. - The Details (default) table view, which shows all the Kubernetes objects (including Flux objects, deployments, pods, services, etc.) managed and deployed through this
kustomization. - The Events tab (shown below), which shows related Kubernetes events to help you diagnose issues and understand health over time.
- The Reconciliation Graph (shown below), which provides an alternative to the Details view and helps you to understand how various objects relate to each other.
- Dependencies, which provides a directional graph to help you clarify any dependencies between objects and ensure that your automations are set up in the correct order.
- Yaml (shown below), which provides a raw dump yaml view on the object as it currently exists inside your cluster. Note that this will be different from what's in your GitOps repository.
- Pipelines
- Alerts
- Providers
TriggerBinding: This resource binds the incoming JSON message to parameter variables.TriggerTemplate: This resource is the template of thePipelineRunthat will be started.EventListener: This resource glues the above two resources together and creates an http listener service.- Pull request strategy: this strategy is used for applications that are delivered via Flux to all environments of a pipeline. Typically, the versions of these applications are stored in Git and therefore pull requests can be used to update them as part of a promotion.
- Notification strategy: this strategy is used when an external CI system is responsible for promoting an application across the environments of a pipeline. In this strategy, the notification controller running on the management cluster is used to forward notifications of successful promotions to external CI systems.
- The namespace of the app's pipeline.
- The name of the pipeline resource.
- The origin environment's name. This is the name of the environment that the event is created in, e.g. "dev" for events coming from the "dev" environment.
- Use it in low-risk environments and not in production: pipelines is an alpha feature and not yet production-ready.
- Make sure you have considered possible attack vectors to production, and put controls in place. Some of these scenarios are:
- In the case of a monorepo: you want to ensure that a compromised token for a test cluster cannot end up doing a promotion in production, without at least a pull request review; for example, by using Codeowners.
- In the case of repo per environment you want to ensure that a pipeline is configured with your test environment repo URL. You also want to ensure that you have segregation of tokens per environment rather than allowing a token to access any environment repo.
-
Only allow creation of RBAC resources from paths where compliance controls are in place. For example, do not allow regular users to create or update RBAC resources; or, if users must create RBAC resources, restrict them by namespace.
-
Follow the principle of "Least Privilege" RBAC as explained in Kubernetes RBAC Good Practices, with emphasis on the following:
- Prefer granting access to specific secrets, rather than granting
listandwatchon secrets as: - Create a user account for pull request changes: this user context would be used to do any git provider operation, and from the security and auditing perspectives, you don't want to impersonate a real user for it.
- Do not use long-live tokens: set an expiration date and rotate them according to your security policy.
- Honour the least privilege principle: avoid having high privilege tokens. Restrict the token to your just your repo and to just the operations required.
- Review the tokens on a regular basis following your git provider recommendations. Ensure that:
- Only the ones that are required are present.
- Tokens close to their expiration date are cycled.
- The first field is the Namespace of the pipeline resource that the app is part of. In the example above this is
pipeline-01. - The second field denotes the name of the pipeline resource.
- The third field is the name of the environment that this specific HelmRelease targets. The environment name in the marker needs to match with the
namefield of one of the environments defined in the pipeline's.spec.environmentsarray. - Pipeline controller receives events via webhook from leaf clusters. An HMAC is used for verification so a shared key should be provided in this case.
- Pipeline controller clones and patches manifests to promote from the pipeline configuration repo. A set of git credentials are required.
- Pipeline controller uses git provider api to create the pull request with the promoted manifests. A Personal Access Token (PAT) needs to be created to interact with pipelines git provider API. This PAT is also used to list pull requests from the configured repository.
- The Git provider token provided in the
tokenfield needs to be given permission to create pull requests in the pipeline's repository (defined in.spec.promotion.strategy.pull-request.url). - The
hmac-keyfield must match the key used for the Provider resource (.spec.secretRef), if specified in the leaf clusters. - Helm
- Kustomize
- Plain kubernetes files
- PolicyConfig which targets a workspace.
- PolicyConfig which targets a namespace.
- PolicyConfig which targets an application in all namespaces.
- PolicyConfig which targets an application in a certain namespace.
- PolicyConfig which targets a kubernetes resource in all namespaces.
- PolicyConfig which targets a kubernetes resource in a specific namespace.
- All configs are applied from low priority to high priority while taking into consideration the common parameters between configs.
- Each config only affects the parameters defined in it.
app-awill be affected bymy-config-5. It will be applied on the policies defined in it, which will affect deploymentdeployment-1in namespaceflux-systemas it matches the kind, name and namespace.- Deployment
deployment-1in namespaceflux-system,replica_countmust be>= 6 - Also it will be affected by
my-config-4forownerconfiguration parameterowner: owner-4 my-config-4will be applied on the policies defined in it which will affect deploymentdeployment-1in all namespaces as it matches the kind and name only.- Deployment
deployment-1in all namespacesreplica_countmust be>= 5 - Also it will be affected by
my-config-4forownerconfiguration parameterowner: owner-4 my-config-3will be applied on the policies defined in it which will affect applicationapp-aand all the resources in it in namespaceflux-systemas it matches the kind, name and namespace.- Application
app-aand all the resources in it in namespacesflux-system,replica_countmust be>= 4 - Also it will be affected by
my-config-1forownerconfiguration parameterowner: owner-1 my-config-2will be applied on the policies defined in it which will affect applicationapp-aand all the resources in it in all namespaces as it matches the kind and name only.- Application
app-aand all the resources in all namespaces,replica_countmust be>= 3 - Also it will be affected by
my-config-1forownerconfiguration parameterowner: owner-1 my-config-1will be applied on the policies defined in it. which will affect the namespaceflux-systemwith all applications and resources in it as it matches by namespace only.- Any application or resource in namespace
flux-system,replica_countmust be>= 2 - Also it will be affected by
my-config-1forownerconfiguration parameterowner: owner-1 - New required field
spec.modeis added. PolicySets should be updated to set the mode - Field
spec.namebecame optional. - Field
spec.idis deprecated. - Agent
- Add support for mutating violating resource.
- Policy Agent v2.2.0
- v1.2.0
- v1.1.0
- v1.0.0
- v0.4.0
- Agent
- Add PolicyConfig CRD to make it possible to customize policy configuration per namespaces, applications or resources
- Add mode field to policy set and add policy modes to its status
- Add policy modes to labels to support filtering
- Support backward compatibility for policy version v2beta1
- Policy Agent v2.0.0
- v1.2.0
- v1.1.0
- v1.0.0
- v0.4.0
- Agent
- Reference flux objects in violations events instead of the original resource object to be able to list specific flux application violations
- policy-agent 1.2.1
- v0.4.0
- v1.0.0
- v1.1.0
- Agent
- Add Terraform mode to allow validating terraform plans
- Support targeting kubernetes HPA resources
- policy-agent 1.2.0
- v0.4.0
- v1.0.0
- v1.1.0
- Agent
- Make the audit interval configurable through
config.audit.interval. It defaults to 24 hours. - Add support for targeting certain flux resources (kustomizations, helmreleases and ocirepositories) in the admission mode.
- Profile
- Add the ability to use an existing GitSource instead of creating a new one.
- policy-agent 1.1.0
- v0.4.0
- v1.0.0
- Agent
- Configure the agent through a configuration file instead of arguments.
- Allow defining different validation sinks for audit and admission modes.
- Add the PolicySet CRD to the hem chart.
- Profile
- Disable the default policy source.
- policy-agent 1.0.0
- v0.4.0
- v1.0.0
accountId: unique identifier that signifies the owner of that agentclusterId: unique identifier for the cluster that the agent will run againstlogLevel: app log level (default: "info")probesListen: address for the probes server to run on (default: ":9000")metricsAddress: address the metric endpoint binds to (default: ":8080")insert: doesn't update or delete any old records. The index will contain a log for all validation objects and give an insight of all the historical data.upsert: updates the old result of validating an entity against a policy that happened on the same day. So the index will only contain the latest validation results for a policy and entity combination per day.- Basic knowledge of Flagger
- An existing
Canaryobject and target deployment - Flagger's load tester installed
- The Official Flagger documentation informs this guide.
- This guide assumes you already have a Kubernetes cluster running and have bootstrapped Flux. To apply the manifests listed here, you will need to commit them to a repository being reconciled with Flux.
- Flagger requires the
autoscaling/v2orautoscaling/v2beta2API to be installed on your cluster. You can usekubectl api-resourcesto check which API versions are supported. - The step CLI installed to generate certificates that support mTLS connections.
- gitops check - Validates flux compatibility
- gitops completion - Generate the autocompletion script for the specified shell
- gitops create - Creates a resource
- gitops delete - Delete a resource
- gitops get - Display one or many Weave GitOps resources
- gitops logs - Get logs for a resource
- gitops replan - Replan a resource
- gitops resume - Resume a resource
- gitops set - Sets one or many Weave GitOps CLI configs or resources
- gitops suspend - Suspend a resource
- gitops version - Display gitops version
- gitops - Weave GitOps
- gitops - Weave GitOps
- gitops completion bash - Generate the autocompletion script for bash
- gitops completion fish - Generate the autocompletion script for fish
- gitops completion powershell - Generate the autocompletion script for powershell
- gitops completion zsh - Generate the autocompletion script for zsh
- gitops completion - Generate the autocompletion script for the specified shell
- gitops completion - Generate the autocompletion script for the specified shell
- gitops completion - Generate the autocompletion script for the specified shell
- gitops completion - Generate the autocompletion script for the specified shell
- gitops - Weave GitOps
- gitops create dashboard - Create a HelmRepository and HelmRelease to deploy Weave GitOps
- gitops create terraform - Create a Terraform object
- gitops create - Creates a resource
- gitops create - Creates a resource
- gitops - Weave GitOps
- gitops delete terraform - Delete a Terraform object
- gitops delete - Delete a resource
- gitops - Weave GitOps
- gitops get bcrypt-hash - Generates a hashed secret
- gitops get config - Prints out the CLI configuration for Weave GitOps
- gitops get - Display one or many Weave GitOps resources
- gitops get - Display one or many Weave GitOps resources
- gitops - Weave GitOps
- gitops logs terraform - Get the runner logs of a Terraform object
- gitops logs - Get logs for a resource
- gitops - Weave GitOps
- gitops replan terraform - Trigger replan for a Terraform object
- gitops replan - Replan a resource
- gitops - Weave GitOps
- gitops resume terraform - Resume a Terraform object
- gitops resume - Resume a resource
- gitops - Weave GitOps
- gitops set config - Set the CLI configuration for Weave GitOps
- gitops set - Sets one or many Weave GitOps CLI configs or resources
- gitops - Weave GitOps
- gitops suspend terraform - Suspend a Terraform object
- gitops suspend - Suspend a resource
- gitops - Weave GitOps
mkdocs new [dir-name]- Create a new project.mkdocs serve- Start the live-reloading docs server.mkdocs build- Build the documentation site.mkdocs -h- Print help message and exit.- EntityFluxDeploymentsCard - shows a combined view of HelmReleases and Kustomizations
- EntityFluxSourcesCard - shows a combined view of GitRepositories, OCIRepositories and HelmRepositories
- EntityFluxHelmReleasesCard
- EntityFluxKustomizationsCard
- EntityFluxGitRepositoriesCard
- EntityFluxOCIRepositoriesCard
- EntityFluxHelmRepositoriesCard
- Raise an issue
- Invite yourself to the Weave Users Slack.
- Chat to us on the #weave-gitops slack channel.
- Set up time with one of our team: James - Product Director (US - East Coast)
- Come along to one of our events
- The specific sub command itself - e.g.
gitops get bcrypt-hash - The name of the flags used, without the value (e.g.
--password, but not the value) - A random string used as an anonymous user ID, stored on your machine
-
- Note: We have no way of tracking individual users. We can only distinguish between user counts and event counts
- Whether the user has installed the Enterprise or open-source version of the CLI
- A value of
app=cli, to know it\u2019s a CLI metric - Your browser, version, and user agent
- The domain name of your server
- Every page interaction, and the time each page is left open
- All button interactions
- The complete URL of every page, including which resource you look at, and searches done
- We can push new content into your browser, to add questions, guides, or more data points
- We send a unique user hash, based on your user name
-
- Note: We are not able to cross-reference unique users between here and anywhere else - not even your command line - but it gives us the ability to distinguish between user counts and event counts.
- Finally, we include a persistent ID representing your cluster, based on a hash of your
kube-systemnamespace uuid -
- Note: There is no way for us to track individual clusters using this, but it gives us the ability to distinguish between cluster counts and event counts.
- GitOps for absolute beginners - eBook from Weaveworks
- Guide to GitOps - from Weaveworks
- Awesome GitOps - inspired by https://github.com/sindresorhus/awesome
- Flux docs - comprehensive documentation on Flux
- OpenGitOps - CNCF Sandbox project aiming to define a vendor-neutral, principle-led meaning of GitOps.
- gitops.tech - supported by Innoq
- Continuous Delivery through GitOps for apps and infrastructure.
- Support for GitHub, GitLab, and Bitbucket; S3-compatible buckets as a source; all major container registries; and all CI workflow providers.
- A secure, pull-based mechanism, operating with least amount of privileges, and adhering to Kubernetes security policies.
- Compatibility with any conformant Kubernetes version and common ecosystem technologies such as Helm, Kustomize, RBAC, Prometheus, OPA, Kyverno, etc.
- Multitenancy, multiple Git repositories, multiple clusters.
- Alerts and notifications.
- Application Operations\u2014manage and automate deployment pipelines for apps and more.
- Easily have your own custom PaaS on cloud or on premise.
- Coordinate Kubernetes rollouts with virtual machines, databases, and cloud services.
- Drill down into more detailed information on any given Flux resource.
- Uncover relationships between resources and quickly navigate between them.
- Understand how workloads are reconciled through a directional graph.
- View Kubernetes events relating to a given object to understand issues and changes.
- Secure access to the dashboard through the ability to integrate with an OIDC provider (such as Dex).
- Enable the monitoring server with the metrics endpoint.
- Install Kube Prometheus Stack.
- Deploy Weave GitOps Monitoring Config
- See the dashboards in Grafana. You can filter by tags
fluxorweave-gitops. - Enable the monitoring server with the profiling endpoint.
- Navigate to your monitoring server URL to the
/debug/pprofpath where the pprof web interface is exposed. - To make a report please email the private security list at security@weave.works with the details. We ask that reporters act in good faith by not disclosing the issue to others.
- Reported vulnerabilities are triaged by Weaveworks Security team.
- Weaveworks Security team would acknowledge to the reporter for any valid request. You will be able to choose if you want public acknowledgement of your effort and how you would like to be credited.
- All reports are thoroughly investigated by the Security Team.
- Any vulnerability information shared with the Security Team will not be shared with others unless it is necessary to fix the issue. Information is shared only on a need to know basis.
- As the security issue moves through the identification and resolution process, the reporter will be notified.
- Additional questions about the vulnerability may also be asked of the reporter.
- One path that shows you how to manage clusters without adding Cluster API. Join a cluster by hooking WGE to it, then install an application on that cluster.
- An optional path that shows you how to create, provision, and delete your first API cluster with EKS/CAPA.
-
the repository used to initially create the resource found in the
templates.weave.works/create-requestannotation (in the case of editing or deleting of resources)metadata:\nannotations:\ntemplates.weave.works/create-request: \"{...\\\"parameter_values\\\":{...\\\"url\\\":\\\"https://github.com/weave-example-org/weave-demo\\\"}\"\n -
the first repository found with a
weave.works/repo-role: defaultannotationmetadata:\nannotations:\nweave.works/repo-role: default\n -
the flux-system repository
metadata:\nname: flux-system\nnamespace: flux-system\n -
the first repository in the list of Git repositories that the user has access to.
github cli>= 2.3.0 (source)kubectl(source)eksctl(source)- the AWS Command Line Interface/
aws cli(source) clusterctl>= v1.1.3 (source); follow these steps to initialise the cluster and enable feature gatesclusterawsadm>= v1.1.0, following Cluster API's instructions- Make sure you have a management cluster. If you followed the Weave GitOps Enterprise installation guide, you'll have done this already.
- Configure your
AWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEYwith eitheraws configureor by exporting it in the current shell. - Set the
GITHUB_TOKENas an environment variable in the current shell. It should have permissions to create Pull Requests against the cluster config repo. - AWS multi-tenancy
- Azure multi-tenancy
- vSphere multi-tenancy
- Select the clusters you want to delete
- Press the
Create a PR to delete clustersbutton - Either update the deletion PR values or leave the default values, depending on your situation
- Press the
Remove clustersbutton - Merge the PR for clusters deletion
- Create a new service account on the remote cluster:
- Add RBAC permissions for the service account:
- Retrieve the token from the service account. First, run this command to get the list of secrets of the service accounts:
- Create a kubeconfig secret. We'll use a helper script to generate the kubeconfig, and then save it into
static-kubeconfig.sh: -
Obtain the cluster certificate (CA). How you do this depends on your cluster.
-
AKS: Visit the Azure user docs for more information.
- EKS: Visit the EKS docs for more information.
- GKE: You can view the CA on the GCP Console: Cluster->Details->Endpoint->\u201dShow cluster certificate\u201d.
-
Update the following fields:
-
CLUSTER_NAME: insert the name of your cluster\u2014i.e.,
demo-01 - ENDPOINT: add the API server endpoint i.e.
34.218.72.31 - CA_CERTIFICATE: include the path to the CA certificate file of the cluster
-
TOKEN: add the token of the service account retrieved in the previous step
-
Finally, create a secret for the generated kubeconfig in the WGE management cluster:
- Authentication strategies
- X509 client certificates: can be used across different namespaces
- Service account tokens: limited to a single namespace
- Kubernetes authentication 101 (CNCF blog post)
- Kubernetes authentication (Magalix blog post)
AWSClusterStaticIdentity:AWSClusterAWSClusterRoleIdentity:AWSClusterAzureClusterIdentity:AzureClusterVSphereClusterIdentity:VSphereCluster- Set up a WGE install environment.
- Collect artifacts and publish to a private registry.
- Install WGE in the air-gapped environment.
- Setup a proxy host
- Setup a private registry
- Install WGE
- docker as container runtime.
- kubectl and kind
- helm
- skopeo to manage container images
- flux to boostrap Flux in the environment.
- clusterctl to replicate the cluster management capabilities.
- Configure the environment variables to your context.
- Execute
maketo automatically sync Helm charts and container images. - Adjust Helm Releases
spec.chart.spec.sourceRefto tell Flux to pull Helm charts from your Helm repo. - Adjust Helm Releases
spec.valuesto use the container images from your private registry. - Configuration: flux-system
- Namespace: flux-system
- Scope: Cluster
apiopenidemailprofilehttps://localhost:8000/oauth/gitlabfor port-forwarding and testinghttps://git.example.com/oauth/gitlabfor production useGIT_HOST_TYPESto tell WGE that the host is gitlabGITLAB_HOSTNAMEwhere the OAuth app is hostedGIT_HOST_TYPESto tell WGE that the host is bitbucket-serverBITBUCKET_SERVER_HOSTNAMEwhere the OAuth app is hosted- Source Kind: Git repository
- Repository URL: [your repository URL here]
- Reference Type: Branch
- Repository Type: Private
- Authentication Source: Provide Authentication here
- SSH Key Authentication: Let the operator generate SSH Keys
- HTTPS User: YOUR_GITHUB_USERNAME
- HTTPS Key: YOUR_GITHUB_USER_PAT (Get one at this link. It's not the most secure method, but the easiest to get going.)
- Click Create
- Instance name: flux-system
- Path: clusters/default/demo3-azure-flux
- Prune: Ticked
- Day 0: you want to get started quickly for discovery with the less knowledge possible.
- Day 1: you have done discovery and want to set it up in your organisation.
- Interactive: guides you step-by-step through the process until Weave GitOps Enterprise is up and running.
- Non-interactive: for your automated workflows where you are already familiar with install process and have the configuration.
- Management Cluster: a Kubernetes cluster with a Kubeconfig that has Admin permissions to be able to create resources.
- Git Repository with SSH access: this is the configuration repo that WeaveGitOps will use to sync configuration manifests from.
- Flux CLI: is installed locally. It will be used for reconciling Flux resources.
- Flux Bootstrapped in your Management cluster via ssh. See Flux Bootstrap for more info.
- Weave GitOps Enterprise Entitlements are installed in the management cluster. Contact Sales for help on getting them.
- Verify Flux: verify Flux installation on the Management cluster.
- Verify Entitlement: verify the Entitlements secret content (username, password, entitlement).
- Configure Git Access: configure the access to your configuration repo.
- Select WGE version: from the latest 3 available releases.
- Create Cluster User: create a Secret with the username and password for the emergency cluster user.
- Configure Dashboard Access: choose between 2 methods to access the dashboard either local or external.
- Access the dashboard: via the link from the installation success message.
- (Optional) Configure OIDC: to enable login to dashboard via OIDC providers.
- Service: this option is called
localhostin the cli and the dashboard will be available through a ClusterIP Service. - Ingress: this option is called
externaldnsthe dashboard will be available through an Ingress with the following considerations:- An Ingress controller needs to exist.
- A host-based ingress will be created of the ingress class
public-nginx. - An ExternalDNS annotation will be added with the value of the provided domain.
--kube-config: allows to choose the Kubeconfig for your cluster, default would be ~/.kube/config-d,--domain externaldns: indicate the domain to use in case of using externaldns-t,--domain-type: dashboard domain type: could be 'localhost' or 'externaldns'-h,--help: help for bootstrap-p,--password: Dashboard admin password-k,--private-key: Private key path. This key will be used to push the Weave GitOps Enterprise's resources to the default cluster repository-c,--private-key-password: Private key password. If the private key is encrypted using password-u,--username: Dashboard admin username-v,--version: Weave GitOps Enterprise version to install- owner: The username (or organization) of the Git repository
- repository: Git repository name
- branch: Git branch (default \"main\")
- path: Path relative to the repository root; when specified, the cluster sync will be scoped to this path
- personal: If set, the owner is assumed to be a repo user
- components-extra: Additional controllers to install
wego-admin- Bound to the
ClusterRole, created by Helm,wego-admin-cluster-role - Aisha is the only member
wego-team-a-admin- Bound to a
Role, using the same permissions aswego-admin-role, created in Team-A's namespace - Brian and Aisha are members
wego-readonly- Bound to a
ClusterRolethat matcheswego-admin-cluster-rolebut with nopatchpermissions. - Aisha, Brian, June and Jo are all members
apiopenidemailprofilehttps://localhost:8000/oauth/gitlabfor port-forwarding and testinghttps://git.example.com/oauth/gitlabfor production useGIT_HOST_TYPESto tell WGE that the host is gitlabGITLAB_HOSTNAMEwhere the OAuth app is hostedGIT_HOST_TYPESto tell WGE that the host is bitbucket-serverBITBUCKET_SERVER_HOSTNAMEwhere the OAuth app is hostedvalues.policy-agent.enabled: set to true to install the agent with WGEvalues.policy-agent.config.accountId: organization name, used as identifiervalues.policy-agent.config.clusterId: unique identifier for the cluster- Cluster Management: We'll show you how to join WGE to a cluster and install an application on that cluster without using Cluster API. But if you prefer using Cluster API, our docs cover that too.
- Install the Terraform Controller to reconcile your Terraform resources in a GitOps way. With Flux and the TF Controller, WGE makes it easy to add Terraform templates to your clusters and continuously reconcile any changes made to the Terraform source manifest.
- Install Policy agent, which comes packaged with the WGE chart.
- Create a service account file:
- Create a roles file:
-
Commit to your fleet repo to sync.
-
Create a secret to store the kubeconfig, and a GitopsCluster object in the WGE management cluster that points to the kubeconfig secret. This allows you to connect to the target cluster and read various Kubernetes objects\u2014including the Flux objects, such as:
- GitRepositories
- HelmReleases
- Kustomizations
- Providers
- Alerts
- Receivers
-
Add a new secret for the service account by adding to the service account yaml file in step 1.
-
Create a kubeconfig secret. We'll use a helper script to generate the kubeconfig, and then save it into
Expand to see script static-kubeconfig.shstatic-kubeconfig.sh:#!/bin/bash\n\nif [[ -z \"$CLUSTER_NAME\" ]]; then\necho \"Ensure CLUSTER_NAME has been set\"\nexit 1\nfi\n\nif [[ -z \"$CA_CERTIFICATE\" ]]; then\necho \"Ensure CA_CERTIFICATE has been set to the path of the CA certificate\"\nexit 1\nfi\n\nif [[ -z \"$ENDPOINT\" ]]; then\necho \"Ensure ENDPOINT has been set\"\nexit 1\nfi\n\nif [[ -z \"$TOKEN\" ]]; then\necho \"Ensure TOKEN has been set\"\nexit 1\nfi\n\nexport CLUSTER_CA_CERTIFICATE=$(cat \"$CA_CERTIFICATE\" | base64)\n\nenvsubst <<EOF\napiVersion: v1\nkind: Config\nclusters:\n- name: $CLUSTER_NAME\n cluster:\n server: https://$ENDPOINT\n certificate-authority-data: $CLUSTER_CA_CERTIFICATE\nusers:\n- name: $CLUSTER_NAME\n user:\n token: $TOKEN\ncontexts:\n- name: $CLUSTER_NAME\n context:\n cluster: $CLUSTER_NAME\n user: $CLUSTER_NAME\ncurrent-context: $CLUSTER_NAME\n\nEOF\n -
Create a secret for the generated kubeconfig in the WGE management cluster:
kubectl create secret generic demo-01-kubeconfig \\\n--from-file=value=./demo-01-kubeconfig\n -
Create a GitopsCluster object. It must NOT be bootstrapped. Remove the annotation for bootstrap so it will not deploy Flux.
-
Commit to your fleet repo and sync.
-
Log in to your WGE management cluster to see if the cluster has appeared.
- ConnectCluster Functionality: Adding the foundation functionality to support connecting leaf clusters via CLI
gitops connect cluster. - Explorer extends source rendering to include OCIRepository resources to be rendered as regular flux sources.
- [UI Enhancement] Improved Top-Right Applied Status and Time Text for Applications and Terraform Details pages.
- flux >v2.0.0
- weave-gitops v0.31.2
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.1
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.5.0
- (optional) gitopssets-controller v0.15.3
- UI token refreshing! OIDC token refreshing is now handled by the UI, this avoids unintentionally making multiple token requests to the OIDC provider. This old behaviour sometimes triggered rate limiting in OIDC providers, causing errors.
- UI polish including removing duplicate error messages and more consistency in headers and font sizes.
- View Policy Audit violations in policies page as a tab
- ClusterGenerator - return labels as generic maps, allows for easily using them in params.
- Handle empty artifacts in directory processing, if a
GitRepositoryorOCIRepositoryhas no artifact, stop generating with an error. - Update the ImagePolicy generator to add the image.
- Ignore empty generators in the Matrix generator, fixing a panic if a generator produced an empty list.
- flux >v2.0.0
- weave-gitops v0.30.0
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.1
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.5.0
- (optional) gitopssets-controller v0.15.3
- flux >v2.0.0
- weave-gitops v0.29.0
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.3.0
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.5.0
- (optional) gitopssets-controller v0.14.1
- PR: #3126 - Uses weave-gitops v0.29.0 that as major changes include:
- Support for Flux v2.0.0
- Suspend/resume/reconcile Image Repositories
- Add Verified sources to Applications and Sources UI
- Using Flux v2.0.0 APIs. Managing
GitRepositoryv1,Kustomizationv1, andReceiverv1 resources. See Breaking Changes. - Generates metrics for indexer write operations
- flux >v2.0.0
- weave-gitops v0.29.0-rc.1
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.3.0
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.5.0
- (optional) gitopssets-controller v0.14.1
- PR: #3137 - Upgrade to Weave GitOps OSS v0.29.0-rc.1 and Flux v2.0.0 APIs
- PR: #3119 - Bump GitOpsSets to v0.14.0
- PR: #3134 - add RED metrics for indexer writes
- PR: #3098 - [UI] Cleanup forms across sections to ensure consistency
- PR: #3145 - Wge 3144 - create sops secrets uses v1 kustomizations api
- PR: #3146 - generate v1 kustomizations when adding apps
- PR: #3164 - Bump gitopssets-controller to v0.14.1
- PR: #3120 - Add large info display of Applied Revision and Last Updated on Terraform detail page
- PR: #3138 - Fix checkboxes on terraform data table
- This release drops the requirement to install cert-manager
- Extends external secrets creation form to allow selecting multiple properties or all properties
- Better support for organising your clusters and templates in the UI via namespaces
- Better support for Azure and Bitbucket Repositories in the UI, you can now click through to Open Pull Requests from these providers
- Dark Mode support for Policy Config
- Adds support for Kubernetes Events
- This version of Weave Gitops Enterprise drops support for
v1alpha1of theCAPITemplateandGitopsTemplateCRDs. Please migrate tov1alpha2of these CRDs. See the migration guide - weave-gitops v0.28.0
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.3.0
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.5.0
- (optional) gitopssets-controller v0.13.4
- Retries to make sure we're showing you the freshest data
- Exports more metrics to enhance observability
- Config generator enabled by default! Include values from ConfigMaps and Secrets in your GitOpsSets
- Dark mode enhancements
- Consistent form styling
- weave-gitops v0.26.0
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.2.0
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.5.0
- (optional) gitopssets-controller v0.13.4
- Dark Mode is now available in WGE.
- Added Prometheus metrics for all API endpoints.
- weave-gitops v0.26.0
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.2.0
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.5.0
- (optional) gitopssets-controller v0.13.2
- weave-gitops v0.25.1-rc.1
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.2.0
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.4.0
- (optional) gitopssets-controller v0.12.0
- GitOpsSets can now generate from Flux Image Automation's
ImagePolicy. This allows you to include the latest version of an image in your templates, for example to keep aDeploymentup to date. - Cross namespace support lands, create resources in multiple namespaces, they'll also be cleaned up properly via finalizers.
- The Sync button in the UI now works correctly
- You can now filter out the versions that will be shown from a HelmRepository when installing a chart via annotations:
\"weave.works/helm-version-filter\": \"> 0.0.0\"to filter out rc releases\"weave.works/helm-version-filter\": \"> 1.0.0\"to filter any pre 1.0 releases\"weave.works/helm-version-filter\": \"> 3.0.0-0\"to filter any pre 3.0 releases but include rc releases- You could now navigate by filters and enabled full-text search.
- Full-text search with terms including special characters like dashes (-) returns more results than expected by exact match term. For example, searching by term \"flux-system\" is treated as two terms: \"flux\" & \"system\" so returns the results for the joint of them. A fix for this will be part of the following releases.
- weave-gitops v0.24.0
- cluster-controller v1.5.2
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.2.0
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.3.0
- (optional) gitopssets-controller v0.12.0
- Health status is now displayed for Kubernetes built-in resources.
- You could configure the service account to use for collecting resources.
- You can now provide a Markdown description of a template. This will be rendered at the top of the Template page allowing template authors to provide clear instructions to their users on how to best fill in the values and complete any other required tests and checks.
- Raw templates are more flexible and allow you to render resources which don't have an explicit
metadata.namefield. - The cluster details page now shows a Cluster's Connectivity status, along with more details for both GitopsClusters and CAPIClusters, including:
- Conditions
- Labels
- Annotations
- When enabled useQueryServiceBackend navigation from Clusters UI to Applications UI is not possible as Explorer does not yet support filtering.
- weave-gitops v0.23.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.2.0
- (optional) pipeline-controller v0.21.0
- (optional) policy-agent v2.3.0
- (optional) gitopssets-controller v0.11.0
- Explorer supports now Flux sources.
- Applications UI and Sources UI could be configured to use Explorer backend to improve UI experience.
- Explorer collector uses impersonation. Ensure you configure collector for your leaf clusters.
- Now supports correctly templating numbers and object chunks
- Don't wait for ControlPlane readiness to sync secrets, this allows secrets to be sync'd related to CNI or other early stage processes
- Explorer: you should configure collector service account in your leaf clusters.
- Clusters page horizontally scrolls too much and status becomes unreadable for some fields
- weave-gitops v0.22.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.6.0
- templates-controller v0.2.0
- (optional) pipeline-controller v0.20.0
- (optional) policy-agent v2.3.0
- (optional) gitopssets-controller v0.9.0
- See your gitopssets on leaf clusters in the UI
- Fixed bug where gitopssets would not update ConfigMaps
- View Open Pull requests button in the UI now allows you to select any GitRepository
- weave-gitops v0.21.2
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.5.0
- templates-controller v0.1.4
- (optional) pipeline-controller v0.20.0
- (optional) policy-agent v2.3.0
- (optional) gitopssets-controller v0.8.0
- weave-gitops v0.20.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.5.0
- templates-controller v0.1.4
- (optional) pipeline-controller v0.20.0
- (optional) policy-agent v2.3.0
- (optional) gitopssets-controller v0.7.0
- Gitopsssets come to the UI!
- weave-gitops v0.19.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- templates-controller v0.1.4
- (optional) pipeline-controller v0.20.0
- (optional) policy-agent v2.3.0
- (optional) gitopssets-controller v0.6.0
- See the logged in user's OIDC groups in the UI via the new User Profile page
- Image Automation pages now show cluster information
- See details about the configured promotion strategy for a pipeline
- Log filtering by source and level for GitOps Run
- See all Policy Configs listed in the UI
- New
clustergenerator allows you to interact with the Weave GitOps Cluster inventory. GitOps Clusters that are added and removed to the inventory are reflected by the generator. That can be used to target for example to manage applications across a fleet of clusters. - Enhanced
gitRepositorygenerator can now scan directories and paths with the newdirectoryoption, which enables you to create for example dynamically Flux Kustomizations , based on your repository. - New
apiClientgenerator allows you to query and endpoint, and provide data for your template. - Reconciliation metrics are now reported to the
/metricsendpoint ready to be collected - weave-gitops v0.18.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- templates-controller v0.1.3
- (optional) pipeline-controller v0.20.0
- (optional) policy-agent v2.3.0
- (optional) gitopssets-controller v0.5.0
- It's becoming easier to create new a external secret CR through the UI instead of writing the whole CR yaml.
- The creation form will help users choose which cluster to deploy the External Secret to and which secret store to sync the secrets from.
- It's all done in the GitOps way.
- Adding Add Plan button in the terraform plan page to enable users to re-plan changes made.
- weave-gitops v0.16.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- templates-controller v0.1.2
- (optional) pipeline-controller v0.14.0
- (optional) policy-agent v2.2.0
- (optional) gitopssets-controller v0.2.0
- Weave GitOps Enterprise, is now supporting via the WGE GUI the selection of the Git Repository. Enabling to scale and match the desired Git Repository structure.
- Supporting path for Profiles, enabling to set the path for profiles in the template to configure where in the directory the HelmRelease gets created.
- Enhanced Enterprise CLI support for GitOps Templates.
- Support for profiles in templates via CLI
gitops create templatesupporting--configallows you to read command line flags from a config file and--output-dirallows you to write files out to a directory instead of just stdout- GitOpsSets enable Platform Operators to have a single definition for an application for multiple environments and a fleet of clusters. A single definition can be used to generate the environment and cluster-specific configuration.
- GitOpsSets has been released as a feature in preview of WGE. The Preview phase helps us to actively collect feedback and use cases, iterating and improving the feature to reach a level of maturity before we call it stable. Please contact us via email or slack if you want to get access to the preview.
- Allows customising the requested scopes via config.oidc.customScopes: \"email,groups,something_else\"
- Token refreshing is now supported
- weave-gitops v0.15.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- (optional) pipeline-controller v0.9.0
- (optional) policy-agent v2.2.0
- We are introducing new functionality into Weave GitOps Enterprise to help observe and manage secrets through external secrets operator (ESO). The new secrets UI will enable customers using ESO to observe and manage external secrets, as well as help them troubleshoot issues during their secrets creation and sync operations. In this release, we are including the ability to list all ExternalSecrets custom resources across multi-cluster environments. Users also will have the ability to navigate to each ExternalSecret and know the details of the secret, its sync status, and the last time this secret has been updated, as well as the latest events associated with the secret.
- Retry promotion on failure. Now if a promotion fails there is an automatic retry functionalty, you can configure the threshold and delay via the CLI.
- Promotion webhook rate limiting. We enable now the configuration of the rate limit for the promotion webhooks.
- weave-gitops v0.14.1
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- (optional) pipeline-controller v0.9.0
- (optional) policy-agent v2.2.0
- GitOps templates now provide the capability to write resources to multiple paths in the Git repository. This feature allows complex scenarios, like for example creating a self-service for an application that requires an RDS database. We\u2019ve provided documentation which has a example.
- Weave GitOps now provides a GUI for Workspaces.
- Weave GitOps now provides more details on the Terraform inventory GUI page. Adding the type and identifier fields to the inventory table, plus filtering and a 'no data' message.
- Weave GitOps now building and printing a list of set up port forwards.
- Weave GitOps now opening the selected port forward URL on key press. Listening for keypress is performed with the
github.com/mattn/go-ttypackage (other options required pressing Enter after a keypress, this catches just a single numeric keypress) and opening URLs with thegithub.com/pkg/browserpackage. - weave-gitops v0.13.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- (optional) pipeline-controller v0.8.0
- (optional) policy-agent v2.2.0
- Support to specify Helm charts inside the CRD, instead of annotations. We\u2019ve provided documentation which has a example.
- Ability to edit all fields now, including name/namespace
- Support Azure DevOps and auto-remediation in commit-time enforcement.
- Weave GitOps default admin user can now \u201cread\u201d all objects. Why is this important? As users are trying out Weave GitOps they will most likely try it out with some of their favorite Cloud Native tools such as Crossplane, Tekton, Istio, etc. This enables them to see all of those resources and explore the full power of Weave GitOps. We still do not recommend this user for \u201cproduction-use\u201d cases, and customers should always be pushed towards implementing OIDC with scoped roles.
- From the Pipelines view you can add new Pipelines in a way which leverages GitOpsTemplates, additionally - to help users configure these, we\u2019ve provided documentation which has some samples.
- Support for running multiple flux instances in different namespaces on a single cluster for resource isolation.
- [UI] Notifications provider page shows a 404.
- We are working towards unifying CAPI and GitOps Templates under a single umbrella. For those already using CAPITemplates, we will ensure a smooth transition is possible by making use of a conversion hooks. There are some breaking changes for GitOpsTemplates as part of this transitionary period, so be sure to check the guidance under Breaking Changes.
- We now retain the ordering of parameters in the template instead of sorting them alphabetically. Providing to the author control in what sequence the parameters are rendered in the form and thus present a more logically grouped set of parameters to the end consumer.
- You can control what delimiters you want to use in a template. This provides flexibility for if you want to use the syntax for dynamic functions like the helper functions we support.
- This feature is now enabled by default when you install the Weave GitOps Enterprise Helm Chart. You can toggle this with the
enablePipelinesflag. - GitOpsTemplates are a highly flexible way to create new resources - including Pipelines. We now provide a shortcut on the Pipelines table view to navigate you to Templates with the
weave.works/template-type=pipelinelabel. - weave-gitops v0.11.0
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- (optional) pipeline-controller v0.0.11
- (optional) policy-agent 2.1.1
- Retain template parameter ordering.
- Allow configuration of the delimiters in templates.
- Add create a pipeline button.
- add missing support for policy version v2beta2 to tenancy cmd.
- weave-gitops v0.10.2
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- (optional) policy-agent 2.1.1
- Create non-cluster resources / Add Edit option to resources with create-request annotation
- bump pipeline-controller
- Parse annotations from template
- Add cost estimate message if available
-
Adds support for showing policy modes and policy configs in the UI
-
Show suspended status on pipelines detail
- YAML view for Pipelines
-
Align and link logo
-
Actually remove the watcher from the helm-watcher-cache
-
UI 1817 disable create target name space if name space is flux system
-
Adding edit capi cluster resource acceptance test
- Add preview acceptance test
- weave-gitops v0.10.1
- cluster-controller v1.4.1
- cluster-bootstrap-controller v0.3.0
- (optional) policy-agent 2.0.0
- When adding applications, you can now preview the changes(PR) before creating a pull request
- You can now see included Cluster Profiles when previewing your Create Cluster PR
- Notifications are now available in the Notifications Page
- You can now automatically create namespace when adding applications
- weave-gitops v0.9.6
- cluster-controller v1.3.2
- cluster-bootstrap-controller v0.3.0
- (optional) policy-agent 1.2.1
- Tenancy
gitops create tenantnow supports--pruneto remove old resources from the cluster if you're not using--exportwith GitOps.deploymentRBACsection intenancy.yamlallows you to specify the permissions given to the fluxKustomizationsthat will apply the resources from git to your tenants' namespaces in the cluster.- Support for
OCIRepositorysources when restricting/allowing the sources that can be applied into tenants' namespaces. - Templates
- Templates now support helm functions for simple transformations of values:
{{ .params.CLUSTER_NAME | upper }} - Templates has moved to its own page in the UI, this is the first step in moving towards embracing them as a more generic feature, not just for cluster creation.
- If a version is not specified in a template profile annotation it can be selected by the user.
- A
namespacecan be specified in the template profile annotation that will be provided as theHelmRelease'stargetNamespaceby default. - Bootstrapping
- A ClusterBootstrapConfig can now optionally be triggered when
phase=\"Provisioned\", rather thanControlPlaneReady=Truestatus. - weave-gitops v0.9.5
- cluster-controller v1.3.2
- cluster-bootstrap-controller v0.3.0
- (optional) policy-agent 1.1.0
- [UI] Notifications page shows a 404 instead of the notification-controller's configuration.
.spec.values.enableExplorer: feature flag to control whether Explorer is enabled..spec.values.useQueryServiceBackend: feature flag to control whether you want to leverage Explorer backend capabilities for other UI experiences like Applications or Sources.spec.values.explorer.collector.serviceAccount: ServiceAccountnameandnamespacethat explorer collector will use to impersonate in leaf clusters. Make sure you read authz for collector before setting it. Default values arename: collector,namespace: flux-system.- HelmRelease
- Kustomizations
- Sources
- GitRepostiories
- OciRepositories
- HelmRepositories
- HelmCharts
- Buckets
- The read or querying path is exercised when a weave gitops user queries the data.
- The write or collecting path is exercised to gather the resources from the leaf clusters.
- Create a ServiceAccount for the one that you specified in your setup
.spec.values.explorer.collector.serviceAccount. - Create a ClusterRole with the permissions to watch the supported resources.
- Create a ClusterRolebinding to assign previous ClusterRole to the created collector
ServiceAccount. - Extend impersonation rules to allow service account impersonation for ServiceAccount
collector - See querying to deep dive in how to query.
- See operations for day troubleshooting and operations.
- You have Weave Gitops Enterprise v0.23.0 or later version
- You have deployed an application.
- A search dialog with filter to querying the platform resources
- A table with the filtered resources.
- API server
- Datastore Reads
- Indexer Reads
actionis the datastore read operation that could be eitherGetObjects,GetAccessRules,GetObjectByID,GetRolesorGetRoleBindings.statusis the result of the operation. It could be either read operation that could be eithersuccessorerror.actionis the datastore read operation that could be eitherGetObjects,GetAccessRules,GetObjectByID,GetRolesorGetRoleBindingsactionis the index read operation that could be eitherListFacetsorSearchstatusis the result of the operation. It could be either read operation that could be eithersuccessorerroractionis the index read operation that could be eitherListFacetsorSearch- Cluster Watcher Manager
- Datastore Writes
- Indexer Writes
actionis the datastore write operation that could be eitherStoreRoles,StoreRoleBindings,StoreObjects,DeleteObjects,DeleteAllObjects,DeleteRoles,DeleteAllRoles,DeleteRoleBindings,DeleteAllRoleBindingsstatusis the result of the operation. It could be either read operation that could be eithersuccessorerroractionis the datastore write operation that could be eitherStoreRoles,StoreRoleBindings,StoreObjects,DeleteObjects,DeleteAllObjects,DeleteRoles,DeleteAllRoles,DeleteRoleBindings,DeleteAllRoleBindingsactionis the index write operation that could be eitherAdd,RemoveorRemoveByQuerystatusis the result of the operation. It could be eithersuccessorerroractionis the index write operation that could be eitherAdd,RemoveorRemoveByQuery- In CI/CD systems where you want to render a template and then use the raw output in a pipeline
- For quickly debugging templates
application- for application templatescluster- for cluster templatesterraform- for Terraform templatespipeline- for Pipeline templatesprofileskustomizationscredentials- Applications:
HelmReleaseKustomization- Sources:
HelmRepositoryGitRepository- Clusters:
GitopsClustername: The variable name within the resource templates.description: Description of the parameter. This will be rendered in both the UI and CLI.options: The list of possible values this parameter can be set to.required- Whether the parameter must contain a non-empty value.default- Default value of the parameter.name- is the name of the profile in the default profiles repositoryversion- (optional) will choose the default versionnamespace- (optional) is the default target namespace for the profileeditable- (optional, default=false), allow the user to de-select this profile, making it a default instead of a requirement.pipeline-view: A template to create a sample pipeline to visualize aHelmReleaseapplication delivered to dev, test and prod environments.pipeline-promotion-resources: A template to create the Flux Notification Controller resources required for promoting applications via pipelines.pipeline-view-promote-by-cluster: A template to create pipelines for hard tenancy when applications are isolated by cluster.pipeline-view-promote-by-namespace: A template to create pipelines for soft tenancy when applications are isolated by namespace.- The path is relative to the repository root
- The path can be templated using params
- The
rawkey is not compatible with thecontentkey. Only one of the two can be used. - The
rawkey data must still be a valid kubernetes unstructured object. templates.weave.works/delimiters: \"{{,}}\"- defaulttemplates.weave.works/delimiters: \"${{,}}\"- Use
${{and}}, for example\"${{ .params.CLUSTER_NAME }}\" - Useful as
{{in yaml is invalid syntax and needs to be quoted. If you need to provide a un-quoted number value likereplicas: 3you should use these delimiters. -replicas: {{ .params.REPLICAS }}Invalid yaml -replicas: \"{{ .params.REPLICAS }}\"Valid yaml, incorrect type. The type is astringnot anumberand will fail validation. -replicas: ${{ .params.REPLICAS }}Valid yaml and correctnumbertype. templates.weave.works/delimiters: \"<<,>>\"- Use
<<and>>, for example<< .params.CLUSTER_NAME >> - Useful if you are nesting templates and need to differentiate between the delimiters used in the inner and outer templates.
- List Generator: The simplest generator. Provide a list of Key/Value pairs that you want to feed the template with.
- Git Generator: Enables you to extract a set of files (environment-specific configurations) from a Flux GitRepository and make their contents available to the templates. This lets you have config in app-dev.json, app-staging.json, and app-production.json, for example.
- Matrix Generator: Combine slices of generators into the desired compounded input.
- Pull request Generator: Automatically discover open pull requests within a repository to generate a new deployment.
- API Client Generator: Poll an HTTP endpoint and parse the result as the generated values.
- OCI Repository
- Cluster
- ImagePolicy
- Config
- Single application definition for different environments (EU-West, North America, Germany)
- Deployment of a single definition across fleet of clusters matching any cluster based on a label (Production)
- Separation of concerns between teams (teams managing different artifacts flowing into a single definition via generators)
- As part of the Weave GitOps Enterprise installation. (installed by default)
- As a standalone installation using a Helm chart.
- Bump client-go to 0.26.8 - avoids a buggy version of the upstream client package
- Fix partial-apply resources bug - errors generating resources could lead to incomplete inventories and errors when regenerating resources
- Bump the memory limits for the Helm chart and document that these may need to be increased.
- Fix bug when a Matrix generator doesn't generate any elements.
- Update the ImagePolicy generator to add the image by splitting the image from the tag.
- Fix bug in the processing of empty artifacts in GitRepositories and OCIRepositories - the directory listing will also return the special empty marker when the Repository is empty.
- ClusterGenerator - return labels as generic maps - this makes it easier to query for labels in a map.
- When a GitRepository or OCIRepository artifact is empty, handle this as a special case that doesn't mean \"no resources\" this prevents removal of resources when the Flux resource hasn't populated yet.
- Support multidoc when rendering via the CLI tool
- Allow custom CAs for the APIGenerator HTTPClient
- Single element Matrix generation - compress multiple Matrix elements into a single element
- Implement element index and repeat index
- Local GitRepository generation from the filesystem in the CLI tool
- Implement OCIGenerator - functionally very similar to the GitRepository generator
- Secrets are now provided in Elements as strings rather than byte slices
- Expose the latest tag not just the latest image in the ImageRepository
- Fix bug in matrix generator when updating GitRepository resources
- Config generator - track Secrets and ConfigMaps and generate from them
- CLI tool for rendering GitOpsSets
- Allow altering the delimiters
- Imagerepository generator by @bigkevmcd in #71
- Allow cross-namespace resources
- Upgrade the matrix to support \"unlimited\" numbers of generators
- Add support for Flux annotation triggered rereconciliation
- Support for using the
repeatmechanism within maps not just arrays - Bump to support Flux v2
- Fail if we cannot find a relevant generator
- Suppress caching of Secrets and ConfigMaps
- Improve APIClient error message
- Support correctly templating numbers - insertion of numeric values is improved
- Add events recording to GitOpsSets
- Fix updating of ConfigMaps
- Implement custom delimiters
- Implement optional list expansion
- Generate all template parameters from the configured generators
- Render all the templates for each set of template parameters
- Nesting GitopsSets within each other, as the default delimiters will conflict
- Providing unquoted values to yaml
- \u274c
replicas: {{ .params.REPLICAS }}Invalid yaml - \u274c
replicas: \"{{ .params.REPLICAS }}\"Valid yaml, incorrect type. The type is a string not a number and will fail validation. - \u2705
replicas: ${{ .params.REPLICAS }}Valid yaml and correct number type. Numberthis is generated as a string representationBranchthis is the source branchHeadSHAthis is the SHA of the commit in the merge branchCloneURLthis is the HTTPS clone URL for this repositoryCloneSSHURLthis is the SSH clone URL for this repositoryForkthis indicates whether the pull request is from a fork (true) or not (false)ClusterNamethe name of the clusterClusterNamespacethe namespace that this cluster is fromClusterLabelsthe labels from the metadata field on the GitOpsClusterClusterAnnotationsthe annotations from the metadata field on the GitOpsCluster- latestImage - the latest image from the status field on the
ImagePolicy - latestTag - only the tag part of the latestImage, e.g. will be v0.1 for an image of \"testing/image:v0.1\"
- previousImage - the previous image from the status field on the
ImagePolicy - sanitize - sanitises strings to be compatible with Kubernetes DNS name requirements
- getordefault - gets a key from the
.Elementor defaults to another value. - The annotation key must start with the domain
metadata.weave.works. Any other annotations will be ignored. - The key that will be displayed is whatever you put after the domain, title cased, and with dashes replaced with spaces. Above,
metadata.weave.works/grafana-dashboardwas displayed as \"Grafana Dashboard\". - The value can either be a link, or can be plain text. Newlines in plain text will be respected.
- The key is subject to certain limitations that kubernetes imposes on annotations, including:
- it must be shorter than 63 characters (not including the domain)
- it must be an English alphanumeric character, or one of
-._. - See the kubernetes documentation for the full list of restrictions.
Flux Beta or Flux v0.xas the latest Flux Beta Release.Flux GAas the latest Flux GA Release CandidateWeave GitOpsas the latest Weave GitOps Enterprise release- EKS Anywhere
- Azure AKS Flux-GitOps extension
- Upgrade to Flux GA on your existing leaf clusters and management clusters
- Upgrade to Flux GA in
ClusterBootstrapConfigs. - Upgrade to latest Weave GitOps.
- Upgrade GitopsTemplates, GitopsSets and ClusterBootstrapConfigs.
- Clone or navigate back to your Git repository where you have bootstrapped Flux. For example:
- Create a
GitRepositorySource for podinfo. This will allow you to use different authentication methods for different repositories. - Commit and push the
podinfo-sourceto yourfleet-infrarepository - Create a
kustomizationto build and apply the podinfo manifest - Commit and push the
podinfo-kustomizationto yourfleet-infrarepository - Add the
patchessection as shown below to the field spec of yourpodinfo-kustomization.yamlfile so it looks like this: - Commit and push the
podinfo-kustomization.yamlchanges: - Navigate back to the dashboard. You should see a newly created pod:
- An account with a Git provider like GitHub or GitLab, along with a personal access token with repo permissions; if you're using GitHub, for example, go here
- Your Git client configured properly (if using GitHub, for example, then review their docs on setting your username and your email address)
- Docker Desktop
- A Kubernetes cluster such as Kind
- kubectl
- A public GitHub repo called
fleet-infra. To create this, follow GitHub\u2019s instructions\u2014usingfleet-infrainstead ofhello-world. - Add Flux component manifests to the repository
- Deploy Flux components to your Kubernetes cluster
- Configure the Flux components to track the path
./clusters/my-cluster/in the repository - use the GitOps CLI tool to generate
HelmReleaseandHelmRepositoryobjects. - create some login credentials to access the dashboard. This is a simple but insecure method of protecting and accessing your GitOps dashboard.
- commit the generated yamls to our
fleet-infrarepo. - observe that they are synced to the cluster.
- If you are running the UI on a subpath, you need to set the
pathfield to the same subpath specified in the--route-prefixflag. - If you have not set a subpath on the weave-gitops server, set the path in the ingress configration to
/. - The Details (default) table view, which shows all the Kubernetes objects (including Flux objects, deployments, pods, services, etc.) managed and deployed through this
kustomization. - The Events tab (shown below), which shows related Kubernetes events to help you diagnose issues and understand health over time.
- The Reconciliation Graph (shown below), which provides an alternative to the Details view and helps you to understand how various objects relate to each other.
- Dependencies, which provides a directional graph to help you clarify any dependencies between objects and ensure that your automations are set up in the correct order.
- Yaml (shown below), which provides a raw dump yaml view on the object as it currently exists inside your cluster. Note that this will be different from what's in your GitOps repository.
- Pipelines
- Alerts
- Providers
TriggerBinding: This resource binds the incoming JSON message to parameter variables.TriggerTemplate: This resource is the template of thePipelineRunthat will be started.EventListener: This resource glues the above two resources together and creates an http listener service.- Pull request strategy: this strategy is used for applications that are delivered via Flux to all environments of a pipeline. Typically, the versions of these applications are stored in Git and therefore pull requests can be used to update them as part of a promotion.
- Notification strategy: this strategy is used when an external CI system is responsible for promoting an application across the environments of a pipeline. In this strategy, the notification controller running on the management cluster is used to forward notifications of successful promotions to external CI systems.
- The namespace of the app's pipeline.
- The name of the pipeline resource.
- The origin environment's name. This is the name of the environment that the event is created in, e.g. \"dev\" for events coming from the \"dev\" environment.
- Use it in low-risk environments and not in production: pipelines is an alpha feature and not yet production-ready.
- Make sure you have considered possible attack vectors to production, and put controls in place. Some of these scenarios are:
- In the case of a monorepo: you want to ensure that a compromised token for a test cluster cannot end up doing a promotion in production, without at least a pull request review; for example, by using Codeowners.
- In the case of repo per environment you want to ensure that a pipeline is configured with your test environment repo URL. You also want to ensure that you have segregation of tokens per environment rather than allowing a token to access any environment repo.
-
Only allow creation of RBAC resources from paths where compliance controls are in place. For example, do not allow regular users to create or update RBAC resources; or, if users must create RBAC resources, restrict them by namespace.
-
Follow the principle of \"Least Privilege\" RBAC as explained in Kubernetes RBAC Good Practices, with emphasis on the following:
- Prefer granting access to specific secrets, rather than granting
listandwatchon secrets as: - Create a user account for pull request changes: this user context would be used to do any git provider operation, and from the security and auditing perspectives, you don't want to impersonate a real user for it.
- Do not use long-live tokens: set an expiration date and rotate them according to your security policy.
- Honour the least privilege principle: avoid having high privilege tokens. Restrict the token to your just your repo and to just the operations required.
- Review the tokens on a regular basis following your git provider recommendations. Ensure that:
- Only the ones that are required are present.
- Tokens close to their expiration date are cycled.
- Review git provider recommendations and examples
- GitHub
- GitLab
- The first field is the Namespace of the pipeline resource that the app is part of. In the example above this is
pipeline-01. - The second field denotes the name of the pipeline resource.
- The third field is the name of the environment that this specific HelmRelease targets. The environment name in the marker needs to match with the
namefield of one of the environments defined in the pipeline's.spec.environmentsarray. - GitHub
- GitLab
- BitBucket Server / DataCenter
- Pipeline controller receives events via webhook from leaf clusters. An HMAC is used for verification so a shared key should be provided in this case.
- Pipeline controller clones and patches manifests to promote from the pipeline configuration repo. A set of git credentials are required.
- Pipeline controller uses git provider api to create the pull request with the promoted manifests. A Personal Access Token (PAT) needs to be created to interact with pipelines git provider API. This PAT is also used to list pull requests from the configured repository.
- The Git provider token provided in the
tokenfield needs to be given permission to create pull requests in the pipeline's repository (defined in.spec.promotion.strategy.pull-request.url). - The
hmac-keyfield must match the key used for the Provider resource (.spec.secretRef), if specified in the leaf clusters. - Github
- Github Enterprise
- Gitlab
- Bitbucket
- Circle CI
- Azure Devops
- Helm
- Kustomize
- Plain kubernetes files
- PolicyConfig which targets a workspace.
- PolicyConfig which targets a namespace.
- PolicyConfig which targets an application in all namespaces.
- PolicyConfig which targets an application in a certain namespace.
- PolicyConfig which targets a kubernetes resource in all namespaces.
- PolicyConfig which targets a kubernetes resource in a specific namespace.
- All configs are applied from low priority to high priority while taking into consideration the common parameters between configs.
- Each config only affects the parameters defined in it.
app-awill be affected bymy-config-5. It will be applied on the policies defined in it, which will affect deploymentdeployment-1in namespaceflux-systemas it matches the kind, name and namespace.- Deployment
deployment-1in namespaceflux-system,replica_countmust be>= 6 - Also it will be affected by
my-config-4forownerconfiguration parameterowner: owner-4 my-config-4will be applied on the policies defined in it which will affect deploymentdeployment-1in all namespaces as it matches the kind and name only.- Deployment
deployment-1in all namespacesreplica_countmust be>= 5 - Also it will be affected by
my-config-4forownerconfiguration parameterowner: owner-4 my-config-3will be applied on the policies defined in it which will affect applicationapp-aand all the resources in it in namespaceflux-systemas it matches the kind, name and namespace.- Application
app-aand all the resources in it in namespacesflux-system,replica_countmust be>= 4 - Also it will be affected by
my-config-1forownerconfiguration parameterowner: owner-1 my-config-2will be applied on the policies defined in it which will affect applicationapp-aand all the resources in it in all namespaces as it matches the kind and name only.- Application
app-aand all the resources in all namespaces,replica_countmust be>= 3 - Also it will be affected by
my-config-1forownerconfiguration parameterowner: owner-1 my-config-1will be applied on the policies defined in it. which will affect the namespaceflux-systemwith all applications and resources in it as it matches by namespace only.- Any application or resource in namespace
flux-system,replica_countmust be>= 2 - Also it will be affected by
my-config-1forownerconfiguration parameterowner: owner-1 - New required field
spec.modeis added. PolicySets should be updated to set the mode - Field
spec.namebecame optional. - Field
spec.idis deprecated. - Agent
- Add support for mutating violating resource.
- Policy Agent v2.2.0
- v1.2.0
- v1.1.0
- v1.0.0
- v0.4.0
- Agent
- Add PolicyConfig CRD to make it possible to customize policy configuration per namespaces, applications or resources
- Add mode field to policy set and add policy modes to its status
- Add policy modes to labels to support filtering
- Support backward compatibility for policy version v2beta1
- Policy Agent v2.0.0
- v1.2.0
- v1.1.0
- v1.0.0
- v0.4.0
- Agent
- Reference flux objects in violations events instead of the original resource object to be able to list specific flux application violations
- policy-agent 1.2.1
- v0.4.0
- v1.0.0
- v1.1.0
- Agent
- Add Terraform mode to allow validating terraform plans
- Support targeting kubernetes HPA resources
- policy-agent 1.2.0
- v0.4.0
- v1.0.0
- v1.1.0
- Agent
- Make the audit interval configurable through
config.audit.interval. It defaults to 24 hours. - Add support for targeting certain flux resources (kustomizations, helmreleases and ocirepositories) in the admission mode.
- Profile
- Add the ability to use an existing GitSource instead of creating a new one.
- policy-agent 1.1.0
- v0.4.0
- v1.0.0
- Agent
- Configure the agent through a configuration file instead of arguments.
- Allow defining different validation sinks for audit and admission modes.
- Add the PolicySet CRD to the hem chart.
- Profile
- Disable the default policy source.
- policy-agent 1.0.0
- v0.4.0
- v1.0.0
accountId: unique identifier that signifies the owner of that agentclusterId: unique identifier for the cluster that the agent will run againstlogLevel: app log level (default: \"info\")probesListen: address for the probes server to run on (default: \":9000\")metricsAddress: address the metric endpoint binds to (default: \":8080\")insert: doesn't update or delete any old records. The index will contain a log for all validation objects and give an insight of all the historical data.upsert: updates the old result of validating an entity against a policy that happened on the same day. So the index will only contain the latest validation results for a policy and entity combination per day.- Basic knowledge of Flagger
- An existing
Canaryobject and target deployment - Flagger's load tester installed
- The Official Flagger documentation informs this guide.
- This guide assumes you already have a Kubernetes cluster running and have bootstrapped Flux. To apply the manifests listed here, you will need to commit them to a repository being reconciled with Flux.
- Flagger requires the
autoscaling/v2orautoscaling/v2beta2API to be installed on your cluster. You can usekubectl api-resourcesto check which API versions are supported. - The step CLI installed to generate certificates that support mTLS connections.
- gitops check - Validates flux compatibility
- gitops completion - Generate the autocompletion script for the specified shell
- gitops create - Creates a resource
- gitops delete - Delete a resource
- gitops get - Display one or many Weave GitOps resources
- gitops logs - Get logs for a resource
- gitops replan - Replan a resource
- gitops resume - Resume a resource
- gitops set - Sets one or many Weave GitOps CLI configs or resources
- gitops suspend - Suspend a resource
- gitops version - Display gitops version
- gitops - Weave GitOps
- gitops - Weave GitOps
- gitops completion bash - Generate the autocompletion script for bash
- gitops completion fish - Generate the autocompletion script for fish
- gitops completion powershell - Generate the autocompletion script for powershell
- gitops completion zsh - Generate the autocompletion script for zsh
- gitops completion - Generate the autocompletion script for the specified shell
- gitops completion - Generate the autocompletion script for the specified shell
- gitops completion - Generate the autocompletion script for the specified shell
- gitops completion - Generate the autocompletion script for the specified shell
- gitops - Weave GitOps
- gitops create dashboard - Create a HelmRepository and HelmRelease to deploy Weave GitOps
- gitops create terraform - Create a Terraform object
- gitops create - Creates a resource
- gitops create - Creates a resource
- gitops - Weave GitOps
- gitops delete terraform - Delete a Terraform object
- gitops delete - Delete a resource
- gitops - Weave GitOps
- gitops get bcrypt-hash - Generates a hashed secret
- gitops get config - Prints out the CLI configuration for Weave GitOps
- gitops get - Display one or many Weave GitOps resources
- gitops get - Display one or many Weave GitOps resources
- gitops - Weave GitOps
- gitops logs terraform - Get the runner logs of a Terraform object
- gitops logs - Get logs for a resource
- gitops - Weave GitOps
- gitops replan terraform - Trigger replan for a Terraform object
- gitops replan - Replan a resource
- gitops - Weave GitOps
- gitops resume terraform - Resume a Terraform object
- gitops resume - Resume a resource
- gitops - Weave GitOps
- gitops set config - Set the CLI configuration for Weave GitOps
- gitops set - Sets one or many Weave GitOps CLI configs or resources
- gitops - Weave GitOps
- gitops suspend terraform - Suspend a Terraform object
- gitops suspend - Suspend a resource
- gitops - Weave GitOps
- You are using Weave Gitops Enterprise version > v0.19.0
- You have a set of GitopsClusters representing the clusters that you want to sync the secret to. They have a set of labels to allow matching.
- You have created a secret that you want to sync from the management cluster.
- Create SecretSync manifests that points to your secret. For example:
-
Check-in to your configuration repo within your management cluster
-
Create a PR, review and merge
-
See the progress
- See the secret created in your leaf cluster
- You have a test Weave Gitops Enterprise environment with Flux installed.
- You have a secret in AWS secrets manager.
- For other setup scenarios using external secrets, see setup ESO
- For SOPS secrets, see setup SOPS
- To discover the UI capabilities to manage secrets, see here
- Status: This indicates the current status of the external secret, which can be \"Ready\" or \"Not Ready\" depending on whether the external secret has been successfully created and is ready for use.
- Last Updated: This shows the date and time when the external secret was last updated.
- External Secret: This is the name of the external secret that you are viewing.
- K8s Secret: This is the name of the Kubernetes secret that is associated with the external secret.
- Cluster: This indicates which cluster the external secret exists on.
- Secret Store: This shows the name of the secret store provider that is being used to store the external secret.
- Secret Store Type: This indicates the type of secret store that is being used to store the external secret. In this case, the type is \"AWS Secrets Manager\".
- Secret path: This is the path to the external secret within the secret store.
-
Version: This shows the version of the external secret, which may be blank if no version has been specified.
-
If the \"Include all properties\" option was selected during the creation of the external secret, this section will display the text \"All properties are included\".
-
If specific properties were manually added during creation, this section will display a table with two columns: \"Property\" and \"SecretKey\". This table lists all the property and secret key pairs added to the external secret.
- Updated: This event indicates that an existing external secret has been successfully updated with new data.
- Not Ready: This event indicates that there was an issue with the secret store when trying to access or synchronize external secrets. This includes situations such as the secret store being unavailable or not ready to handle requests, or issues with authentication when trying to access the secret store.
SOPS_KUSTOMIZATION_NAME: This Kustomization will be used to decrypt SOPS secrets from this pathclusters/default/leaf-cluster/sops/after reconciling on the cluster. example (my-secrets)SOPS_SECRET_REF: The private key secret name that will be generated by SOPS in the bootstrap job. example (sops-gpg)SOPS_SECRET_REF_NAMESPACE: The private key secret namespace this secret will be generated by SOPS in the bootstrap job. example (flux-system)SOPS_KEY_NAME: SOPS key name. This will be used to generate SOPS keys. example (test.yourdomain.com)SOPS_KEY_COMMENT: SOPS key comment. This will be used to generate SOPS keys. example (sops secret comment)SOPS_PUSH_TO_GIT: Option to push the public key to the git repository. expected values (true,false)- A leaf cluster created with Flux & SOPS bootstrapped
- A secret created on leaf cluster
sops-gpgto decrypt secrets - A secret created on leaf cluster
sops-gpg-pubto encrypt secrets - A Kustomization with
decryptiondefined in it toSOPSlocation in the cluster repo location - Added Role for the public key to be accessed through management cluster
- A PR is created to the cluster repo with the public key and SOPS creation rules (optional)
- Visit the Secrets Page and start managing your secrets via the UI
- Create a new Kubernetes role that grants read access to sops decryption secrets
- Bind the role to the service account of the flux's kustomize-controller
- Drift Detection: Use GitOps for drift detection so that you can decide which actions to take when drift occurs.
- GitOps Automation: Fully automate the GitOps process, including provisioning and enforcement, for all of your Terraform resources.
- Hybrid GitOps Automation: GitOps-ify certain parts of your existing infrastructure resources, such as a nodegroup or security group in an existing EKS cluster.
- State Enforcement: Use GitOps to enforce an existing
tfstatewithout making any other changes. - Multi-Tenancy: TF-controller supports multi-tenancy by running Terraform
planandapplyinside Runner Pods. When specifying.metadata.namespaceand.spec.serviceAccountName, the Runner Pod uses the specified ServiceAccount and runs inside the specified Namespace. These settings enable the soft multi-tenancy model, usable within the Flux multi-tenancy setup. - GitOps Automation for Terraform: Setting
.spec.approvePlan=autoallows aTerraformobject to be reconciled and act as the representation of your Terraform resources. TF-controller uses the spec of theTerraformobject toplanandapplyits associated Terraform resources. It then stores theTFSTATEof the applied resources as aSecretinside the Kubernetes cluster. After.spec.intervalpasses, TF-Controller checks for drift between your live system and your Terraform resources and, if affirmative, automatically generates and applies a plan to correct it. - Drift detection: Enabled by default, and part of the GitOps automation feature, the controller detects and fixes infrastructure drift based on the Terraform resources and their
TFSTATE. You can use the field.spec.disableDriftDetectionto disable this behaviour. Drift detection-only mode, withoutplanorapplysteps, allows you to perform read-only drift detection. - Plan and Manual Approve: Separate the
planfrom theapplystep, just like in the Terraform workflow you are familiar with\u2014but in a GitOps way. When a plan is generated, the controller shows you a message asking if you want to apply it. Optionally create and push the change to a new branch for your team members to review and approve too. - YAML-based Terraform: The
Terraformobject in v0.13.0+ allows you to better configure your Terraform resources via YAMLs, but without introducing any extra CRDs to your cluster. - First-class Terraform Cloud Support: Use
spec.cloudto configureTerraformobjects to use Terraform Cloud as the backend for storing the state. - Install Flux v0.32.0 or later on your cluster. This includes installing the Flux CLI on your local machine and installing the Flux controllers on the cluster.
- Configure the network firewall or security groups on your cluster to allow incoming connections to port 30000 on each Runner's Pod in each namespace. This will allow the Controller to communicate with the Runner's Pod via gRPC.
- Configure the network firewall or security groups on your cluster to allow the Controller to download tar.gz BLOBs from the Source controller via port 80 and to post events to the Notification controller via port 80.
-
Create a local cluster using a tool such as
kindorminikube. This will allow you to develop and test TF-Controller in a local environment before deploying it to a production cluster.kind create cluster --name tf-controller\n -
Install the Flux CLI on your local machine. This will allow you to interact with the Flux controllers on your cluster.
brew install fluxcd/tap/flux\n -
Prepare a Git repository to store the configuration files and manifests for Flux and TF-controller. For this example we'll use GitHub. To follow along, you'll need a GitHub account and personal access token with repo permissions. You'll also need to properly configure your Git client by setting your username and email address.
-
Bootstrap the cluster with Flux v2 (v0.32.0 or later) using the path (for example)
./cluster/my-cluster. This will install Flux on the cluster and create a Flux system at./cluster/my-cluster/flux-system.git clone git@github.com:$GITHUB_USER/gitops-tf-controller.git\ncd gitops-tf-controller\n\nflux bootstrap github \\\n--owner=$GITHUB_USER \\\n--repository=gitops-tf-controller \\\n--branch=main \\\n--path=./cluster/my-cluster \\\n--personal \\\n--token-auth\n -
Create a directory at
./cluster/my-cluster/infra/: - In the same directory, create a
kustomization.yamlfile that contains the following: - A Terraform GitOps with Flux to automatically reconcile your AWS IAM Policies.
- GitOps an existing EKS cluster by partially importing its nodegroup and managing it with TF-controller: An EKS scaling example.
- Install Weave GitOps Enterprise and enable TLS.
- Install Terraform Controller.
- Everything from the previous section
- Get (or create) an AWS Access Key ID and Secret Access Key. Check the AWS docs for details on how to do this.
- Create an AWS IAM Role for the Terraform AWS Provider. Its policy should include
iam:CreateRole. More info here. - all the necessary YAML configuration files necessary for tenant setup
- a list of policies that apply to each workspace
- the list of repositories to which each workspace has access.
gitopscommand line tool- Tenancy File (optional)
- Policies (optional)
namespaces: describes which namespaces should be part of the tenant. Meaning that users who are part of the tenant would have access on those namespaces.allowedRepositories: limits thefluxrepositories sources that can be used in the tenant's namespaces. This is done through policies and thus requirespolicy-agentto be deployed on the cluster which will stop these sources from being deployed if they aren't allowed as part of the tenant. IT consists of:kind: thefluxsource kind. Can be:GitRepository,BucketandHelmRepository.url: the URL for that source.allowedClusters: limits which secrets containing cluster configuraton can be used. It stops WGEGitopsClusterand fluxKustomizationfrom being deployed if they point to a secret not in the list, essentially giving control on which cluster can be added to a multi-cluster setup. Requirespolicy-agent.kubeConfig: name of the secret that can be used for this tenant.teamRBAC: Generate Roles and Rolebindings for a list ofgroupNames. This allows you to easily give an OIDC group access to a tenant's resources. When the Weave Gitops Enterprise UI is configured with your OIDC provider, tenants can log in and view the status of the resources they have been granted access to.deploymentRBAC: generate Roles and Rolebindings for a service account. Can additionally bind to an existing Roles/ClusterRoles. Would use the global service account if specified in the tenants file, otherwise it will use the created service account which takes the tenant name. If not specified a Rolebinding would be created that binds tocluster-adminClusterRole.serviceAccount: Override the name of the generatedServiceAccountfor all tenants. This allows you to easily use the flux controllers'--default-service-accountfeature. Tenants do not need to make sure they correctly specify theserviceAccountwhen usingKustomizationorHelmReleaseresources. The kustomization-controller and helm-controller will instead look for thedefault-service-accountin the namespace being reconciled to and use that. Just configureserviceAccount.nameand--default-service-accountto the same value.- You are using Weave Gitops Enterprise version > v0.19.0
- You have a set of GitopsClusters representing the clusters that you want to sync the secret to. They have a set of labels to allow matching.
- You have created a secret that you want to sync from the management cluster.
- Create SecretSync manifests that points to your secret. For example:
-
Check-in to your configuration repo within your management cluster
-
Create a PR, review and merge
-
See the progress
- See the secret created in your leaf cluster
- You have a test Weave Gitops Enterprise environment with Flux installed.
- You have a secret in AWS secrets manager.
- For other setup scenarios using external secrets, see setup ESO
- For SOPS secrets, see setup SOPS
- To discover the UI capabilities to manage secrets, see here
- Status: This indicates the current status of the external secret, which can be "Ready" or "Not Ready" depending on whether the external secret has been successfully created and is ready for use.
- Last Updated: This shows the date and time when the external secret was last updated.
- External Secret: This is the name of the external secret that you are viewing.
- K8s Secret: This is the name of the Kubernetes secret that is associated with the external secret.
- Cluster: This indicates which cluster the external secret exists on.
- Secret Store: This shows the name of the secret store provider that is being used to store the external secret.
- Secret Store Type: This indicates the type of secret store that is being used to store the external secret. In this case, the type is "AWS Secrets Manager".
- Secret path: This is the path to the external secret within the secret store.
-
Version: This shows the version of the external secret, which may be blank if no version has been specified.
-
Properties¶
-
If the "Include all properties" option was selected during the creation of the external secret, this section will display the text "All properties are included".
-
If specific properties were manually added during creation, this section will display a table with two columns: "Property" and "SecretKey". This table lists all the property and secret key pairs added to the external secret.
- Updated: This event indicates that an existing external secret has been successfully updated with new data.
- Not Ready: This event indicates that there was an issue with the secret store when trying to access or synchronize external secrets. This includes situations such as the secret store being unavailable or not ready to handle requests, or issues with authentication when trying to access the secret store.
SOPS_KUSTOMIZATION_NAME: This Kustomization will be used to decrypt SOPS secrets from this pathclusters/default/leaf-cluster/sops/after reconciling on the cluster. example (my-secrets)SOPS_SECRET_REF: The private key secret name that will be generated by SOPS in the bootstrap job. example (sops-gpg)SOPS_SECRET_REF_NAMESPACE: The private key secret namespace this secret will be generated by SOPS in the bootstrap job. example (flux-system)SOPS_KEY_NAME: SOPS key name. This will be used to generate SOPS keys. example (test.yourdomain.com)SOPS_KEY_COMMENT: SOPS key comment. This will be used to generate SOPS keys. example (sops secret comment)SOPS_PUSH_TO_GIT: Option to push the public key to the git repository. expected values (true,false)- A leaf cluster created with Flux & SOPS bootstrapped
- A secret created on leaf cluster
sops-gpgto decrypt secrets - A secret created on leaf cluster
sops-gpg-pubto encrypt secrets - A Kustomization with
decryptiondefined in it toSOPSlocation in the cluster repo location - Added Role for the public key to be accessed through management cluster
- A PR is created to the cluster repo with the public key and SOPS creation rules (optional)
- Visit the Secrets Page and start managing your secrets via the UI
- Create a new Kubernetes role that grants read access to sops decryption secrets
- Bind the role to the service account of the flux's kustomize-controller
- To make a report please email the private security list at security@weave.works with the details. We ask that reporters act in good faith by not disclosing the issue to others.
- Reported vulnerabilities are triaged by Weaveworks Security team.
- Weaveworks Security team would acknowledge to the reporter for any valid request.
You will be able to choose if you want public acknowledgement of your effort and how you would like to be credited. - All reports are thoroughly investigated by the Security Team.
- Any vulnerability information shared with the Security Team will not be shared with others unless it is necessary to fix the issue. Information is shared only on a need to know basis.
- As the security issue moves through the identification and resolution process, the reporter will be notified.
- Additional questions about the vulnerability may also be asked of the reporter.
- Install Flux v0.32.0 or later on your cluster. This includes installing the Flux CLI on your local machine and installing the Flux controllers on the cluster.
- Configure the network firewall or security groups on your cluster to allow incoming connections to port 30000 on each Runner's Pod in each namespace. This will allow the Controller to communicate with the Runner's Pod via gRPC.
- Configure the network firewall or security groups on your cluster to allow the Controller to download tar.gz BLOBs from the Source controller via port 80 and to post events to the Notification controller via port 80.
-
Create a local cluster using a tool such as
kindorminikube. This will allow you to develop and test TF-Controller in a local environment before deploying it to a production cluster.kind create cluster --name tf-controller + -
Install the Flux CLI on your local machine. This will allow you to interact with the Flux controllers on your cluster.
brew install fluxcd/tap/flux + -
Prepare a Git repository to store the configuration files and manifests for Flux and TF-controller. For this example we'll use GitHub. To follow along, you'll need a GitHub account and personal access token with repo permissions. You'll also need to properly configure your Git client by setting your username and email address.
-
Bootstrap the cluster with Flux v2 (v0.32.0 or later) using the path (for example)
./cluster/my-cluster. This will install Flux on the cluster and create a Flux system at./cluster/my-cluster/flux-system.git clone git@github.com:$GITHUB_USER/gitops-tf-controller.git +cd gitops-tf-controller + +flux bootstrap github \ + --owner=$GITHUB_USER \ + --repository=gitops-tf-controller \ + --branch=main \ + --path=./cluster/my-cluster \ + --personal \ + --token-auth + -
Create a directory at
./cluster/my-cluster/infra/: - In the same directory, create a
kustomization.yamlfile that contains the following: - A Terraform GitOps with Flux to automatically reconcile your AWS IAM Policies.
- GitOps an existing EKS cluster by partially importing its nodegroup and managing it with TF-controller: An EKS scaling example.
- Drift Detection: Use GitOps for drift detection so that you can decide which actions to take when drift occurs.
- GitOps Automation: Fully automate the GitOps process, including provisioning and enforcement, for all of your Terraform resources.
- Hybrid GitOps Automation: GitOps-ify certain parts of your existing infrastructure resources, such as a nodegroup or security group in an existing EKS cluster.
- State Enforcement: Use GitOps to enforce an existing
tfstatewithout making any other changes. - Multi-Tenancy: TF-controller supports multi-tenancy by running Terraform
planandapplyinside Runner Pods. When specifying.metadata.namespaceand.spec.serviceAccountName, the Runner Pod uses the specified ServiceAccount and runs inside the specified Namespace. These settings enable the soft multi-tenancy model, usable within the Flux multi-tenancy setup. - GitOps Automation for Terraform: Setting
.spec.approvePlan=autoallows aTerraformobject to be reconciled and act as the representation of your Terraform resources. TF-controller uses the spec of theTerraformobject toplanandapplyits associated Terraform resources. It then stores theTFSTATEof the applied resources as aSecretinside the Kubernetes cluster. After.spec.intervalpasses, TF-Controller checks for drift between your live system and your Terraform resources and, if affirmative, automatically generates and applies a plan to correct it. - Drift detection: Enabled by default, and part of the GitOps automation feature, the controller detects and fixes infrastructure drift based on the Terraform resources and their
TFSTATE. You can use the field.spec.disableDriftDetectionto disable this behaviour. Drift detection-only mode, withoutplanorapplysteps, allows you to perform read-only drift detection. - Plan and Manual Approve: Separate the
planfrom theapplystep, just like in the Terraform workflow you are familiar with—but in a GitOps way. When a plan is generated, the controller shows you a message asking if you want to apply it. Optionally create and push the change to a new branch for your team members to review and approve too. - YAML-based Terraform: The
Terraformobject in v0.13.0+ allows you to better configure your Terraform resources via YAMLs, but without introducing any extra CRDs to your cluster. - First-class Terraform Cloud Support: Use
spec.cloudto configureTerraformobjects to use Terraform Cloud as the backend for storing the state. - Install Weave GitOps Enterprise and enable TLS.
- Install Terraform Controller.
- Everything from the previous section
- Get (or create) an AWS Access Key ID and Secret Access Key. Check the AWS docs for details on how to do this.
- Create an AWS IAM Role for the Terraform AWS Provider. Its policy should include
iam:CreateRole. More info here. - all the necessary YAML configuration files necessary for tenant setup
- a list of policies that apply to each workspace
- the list of repositories to which each workspace has access.
gitopscommand line tool- Tenancy File (optional)
- Policies (optional)
namespaces: describes which namespaces should be part of the tenant. Meaning that users who are part of the tenant would have access on those namespaces.allowedRepositories: limits thefluxrepositories sources that can be used in the tenant's namespaces. This is done through policies and thus requirespolicy-agentto be deployed on the cluster which will stop these sources from being deployed if they aren't allowed as part of the tenant. IT consists of:kind: thefluxsource kind. Can be:GitRepository,BucketandHelmRepository.url: the URL for that source.allowedClusters: limits which secrets containing cluster configuraton can be used. It stops WGEGitopsClusterand fluxKustomizationfrom being deployed if they point to a secret not in the list, essentially giving control on which cluster can be added to a multi-cluster setup. Requirespolicy-agent.kubeConfig: name of the secret that can be used for this tenant.teamRBAC: Generate Roles and Rolebindings for a list ofgroupNames. This allows you to easily give an OIDC group access to a tenant's resources. When the Weave Gitops Enterprise UI is configured with your OIDC provider, tenants can log in and view the status of the resources they have been granted access to.deploymentRBAC: generate Roles and Rolebindings for a service account. Can additionally bind to an existing Roles/ClusterRoles. Would use the global service account if specified in the tenants file, otherwise it will use the created service account which takes the tenant name. If not specified a Rolebinding would be created that binds tocluster-adminClusterRole.serviceAccount: Override the name of the generatedServiceAccountfor all tenants. This allows you to easily use the flux controllers'--default-service-accountfeature. Tenants do not need to make sure they correctly specify theserviceAccountwhen usingKustomizationorHelmReleaseresources. The kustomization-controller and helm-controller will instead look for thedefault-service-accountin the namespace being reconciled to and use that. Just configureserviceAccount.nameand--default-service-accountto the same value.- +GitOpsSet +
Backstage
Are you running Backstage and Flux? Do you want to expose the state of your Flux resources in your Backstage portal?
The @weaveworksoss/backstage-plugin-flux Backstage plugin provides a set of components that you can add to your existing Backstage app to display the state of Flux resources.
Installation¶
We provide the full installation instructions in the plugin repository. But first you will need to install the Kubernetes plugin and configure it to access the clusters you want to query Flux resources from.
You will need to install the plugin to your frontend app:
# From your Backstage root directory
+yarn add --cwd packages/app @weaveworksoss/backstage-plugin-flux
+Then add the components you want to your EntityPage.
Currently, the Backstage plugin provides the following components:
For example, to add the EntityFluxHelmReleasesCard to your Entity home page for components with the backstage.io/kubernetes-id entity annotation.
packages/app/src/components/catalog/EntityPage.tsx
import {
+ EntityFluxHelmReleasesCard,
+} from '@weaveworksoss/backstage-plugin-flux';
+import { isKubernetesAvailable } from '@backstage/plugin-kubernetes';
+
+const overviewContent = (
+ <Grid item md={6}>
+ <EntityAboutCard variant="gridItem" />
+ </Grid>
+
+ <EntitySwitch>
+ <EntitySwitch.Case if={isKubernetesAvailable}>
+ <EntityFluxHelmReleasesCard />
+ </EntitySwitch.Case>
+ </EntitySwitch>
+);
+When you view components with the correct annotation:
apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: catalogue-service
+ description: A microservices-demo service that provides catalogue/product information
+ annotations:
+ backstage.io/kubernetes-id: podinfo
+This will query across your configured clusters for HelmReleases that have the correct label:
apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+ name: podinfo
+ namespace: podinfo
+ # The label here is matched to the Backstage Entity annotation
+ labels:
+ backstage.io/kubernetes-id: podinfo
+spec:
+ interval: 5m
+ chart:
+ spec:
+ chart: podinfo
+ version: '6.3.6'
+ sourceRef:
+ kind: HelmRepository
+ name: podinfo
+ namespace: podinfo
+
Building a Custom Page with Resources¶
Instead of displaying the state on the overview page, it's possible to compose a page displaying the state of resources.
For example, to add a page /kustomizations to your Entity for components with the backstage.io/kubernetes-id entity annotation:
packages/app/src/components/catalog/EntityPage.tsx
import {
+ EntityFluxGitRepositoriesCard,
+ EntityFluxKustomizationsCard,
+} from '@weaveworksoss/backstage-plugin-flux';
+import { isKubernetesAvailable } from '@backstage/plugin-kubernetes';
+
+const serviceEntityPage = (
+ // insert in the page where you need it
+
+ <EntityLayout.Route path="/kustomizations" title="Kustomizations" if={isKubernetesAvailable}>
+ <Grid container spacing={3} alignItems="stretch">
+ <Grid item md={12}>
+ <EntityFluxKustomizationsCard />
+ </Grid>
+ <Grid item md={12}>
+ <EntityFluxGitRepositoriesCard />
+ </Grid>
+ </Grid>
+ </EntityLayout.Route>
+);
+
Connecting to Weave GitOps¶
You can connect the plugin to your Weave GitOps installation through your config:
app-config.yaml
app:
+ title: Backstage Example App
+ baseUrl: http://localhost:3000
+...
+gitops:
+ # Set this to be the root of your Weave GitOps application
+ baseUrl: https://example.com
+NOTE: The plugin will generate URLs relative to this URL and link to them from the displayed resources.
How to Inject Credentials Into Your Template ENTERPRISE¶
Weave GitOps templates describe the properties of your cluster—how many nodes, what version of Kubernetes, etc. The identity refers to which account will be used to create the cluster. When you render a template, you may want to set the credentials to be used for this cluster—for example, if the cost is allocated to a specific team.
The rendered resource can be automatically configured with the selected credentials.
Credentials are injected into the following resources: * AWSCluster, AWSManagedControlPlane * AzureCluster, AzureManagedCluster * VSphereCluster
If no credentials are selected, no changes will be applied, and the credentials used by your CAPI controller will be used as the default.
In our cluster we have the template:
apiVersion: templates.weave.works/v1alpha2
+kind: GitOpsTemplate
+metadata:
+ name: capa-cluster-template
+spec:
+ resourcetemplates:
+ - contents:
+ - apiVersion: infrastructure.cluster.x-k8s.io/v1alpha4
+ kind: AWSCluster
+ metadata:
+ name: "${CLUSTER_NAME}"
+ spec:
+ region: "${AWS_REGION}"
+and the identity
apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
+kind: AWSClusterStaticIdentity
+metadata:
+ name: "test-account"
+spec:
+ secretRef:
+ name: test-account-creds
+ namespace: capa-system
+ allowedNamespaces:
+ selector:
+ matchLabels:
+ cluster.x-k8s.io/ns: "testlabel"
+We can select Weave GitOps to use the test-account when creating the cluster by using the Infrastructure provider credentials dropdown on the Create new cluster with template page:
The resulting definition will have the identity injected into the appropriate place in the template, for this example:
apiVersion: infrastructure.cluster.x-k8s.io/v1alpha4
+kind: AWSCluster
+metadata:
+ name: example-cluster
+spec:
+ region: eu-north-1
+ identityRef:
+ kind: AWSClusterStaticIdentity
+ name: test-account
+identityRefs¶
The supported providers implement multi-tenancy by setting an identityRef on the the provider cluster object, e.g. AWSCluster, AzureCluster or VSphereCluster.
Weave GitOps will search all namespaces in the cluster for potential identities that can be used to create a cluster. The following identity kinds are currently supported and their corresponding Cluster kinds:
Cluster Management Troubleshooting ENTERPRISE¶
We'll use this page to help you move past common troublesome situations.
Git Repositories and Resources¶
To authenticate using Git during the pull request creation, you will need to select the Git repository where you'll create the pull request.
Depending on the action performed on the resource (creation/deletion/editing), the default Git repository selected in the UI is determined in the following order:
In the case of deletion and editing, if the resource repository is found amongst the Git repositories that the user has access to, it will be preselected and the selection will be disabled. If it is not found, you can choose a new repository.
In the case of tenants, we recommend adding the weave.works/repo-role: default to an appropriate Git repository.
Overriding the Calculated Git Repository HTTPS URL¶
The system will try and automatically calculate the correct HTTPS API endpoint to create a pull request against. For example, if the Git repository URL is ssh://git@github.com/org/repo.git, the system will try and convert it to https://github.com/org/repo.git.
However, it is not always possible to accurately derive this URL. An override can be specified to set the correct URL instead. For example, the SSH URL may be ssh://git@interal-ssh-server:2222/org/repo.git and the correct HTTPS URL may be https://gitlab.example.com/org/repo.git.
In this case, we set the override via the weave.works/repo-https-url annotation on the GitRepository object:
apiVersion: source.toolkit.fluxcd.io/v1beta1
+kind: GitRepository
+metadata:
+ name: repo
+ namespace: flux-system
+ annotations:
+ // highlight-start
+ weave.works/repo-https-url: https://gitlab.example.com/org/repo.git
+ // highlight-end
+spec:
+ interval: 1m
+ url: ssh://git@interal-ssh-server:2222/org/repo.git
+The pull request will then be created against the correct HTTPS API.
The above also applies to application creation.
Deploying CAPA with EKS ENTERPRISE¶
Weave GitOps Enterprise can leverage Cluster API providers to enable leaf cluster creation. Cluster API provides declarative APIs, controllers, and tooling to manage the lifecycle of Kubernetes clusters across a large number of infrastructure providers. Cluster API custom resource definitions (CRDs) are platform-independent as each provider implementation handles the creation of virtual machines, VPCs, networks, and other required infrastructure parts—enabling consistent and repeatable cluster deployments.
As an AWS advanced technology partner, Weaveworks has been working tirelessly to ensure that deploying EKS anywhere is smooth and removes the barriers to application modernization.
Prerequisites¶
You'll need to install the following software before continuing with these instructions:
Multitenancy¶
Some Cluster API providers allow you to choose the account or identity that the new cluster will be created with. This is often referred to as Multi-tenancy in the CAPI world. Weave GitOps currently supports:
1. Add Common RBAC to Your Repository¶
When a cluster is provisioned, by default it will reconcile all the manifests in ./clusters/<cluster-namespace>/<cluster-name> and ./clusters/bases.
To display Applications and Sources in the UI we need to give the logged in user permissions to inspect the new cluster.
Adding common RBAC rules to ./clusters/bases/rbac is an easy way to configure this!
import WegoAdmin from "!!raw-loader!./assets/rbac/wego-admin.yaml";
curl -o clusters/bases/rbac/wego-admin.yaml https://docs.gitops.weave.works/assets/files/wego-admin-c80945c1acf9908fe6e61139ef65c62e.yaml
+Expand to see full template yaml
clusters/bases/rbac/wego-admin.yaml
+<CodeBlock title="clusters/bases/rbac/wego-admin.yaml" className="language-yaml"
{WegoAdmin}
2. Build a Kubernetes Platform with Built-in Components Preconfigured for Your Organization¶
To do this, go to Weaveworks' Profiles Catalog.
See CAPI Templates page for more details on this topic. Once we load a template we can use it in the UI to create clusters!
import CapaTemplate from "!!raw-loader!./assets/templates/capa-template.yaml";
Download the template below to your config repository path, then commit and push to your Git origin.
curl -o clusters/management/capi/templates/capa-template.yaml https://docs.gitops.weave.works/assets/files/capa-template-49001fbae51e2a9f365b80caebd6f341.yaml
+clusters/management/apps/capi/templates/capa-template.yaml
{% include '/assets/templates/capa-template.yaml' %}
+<CodeBlock title="clusters/management/apps/capi/templates/capa-template.yaml" className="language-yaml"
{CapaTemplate}
3. Add a Cluster Bootstrap Config¶
This step ensures that Flux gets installed into your cluster. Create a cluster bootstrap config as follows:
kubectl create secret generic my-pat --from-literal GITHUB_TOKEN=$GITHUB_TOKEN
+import CapiGitopsCDC from "!!raw-loader!./assets/bootstrap/capi-gitops-cluster-bootstrap-config.yaml";
Download the config with:
curl -o clusters/management/capi/bootstrap/capi-gitops-cluster-bootstrap-config.yaml https://docs.gitops.weave.works/assets/files/capi-gitops-cluster-bootstrap-config-d9934a1e6872a5b7ee5559d2d97a3d83.yaml
+Then update the GITOPS_REPO variable to point to your cluster
Expand to see full yaml
clusters/management/capi/boostrap/capi-gitops-cluster-bootstrap-config.yaml
+<CodeBlock title="clusters/management/capi/boostrap/capi-gitops-cluster-bootstrap-config.yaml" className="language-yaml"
{CapiGitopsCDC}
4. Delete a Cluster with the Weave GitOps Enterprise UI¶
Here are the steps:
Note that you can't apply an empty repository to a cluster. If you have Cluster API clusters and other manifests committed to this repository, and then delete all of them so there are zero manifests left, then the apply will fail and the resources will not be removed from the cluster. A workaround is to add a dummy ConfigMap back to the Git repository after deleting everything else so that there is at least one manifest to apply.
5. Disable CAPI Support¶
If you do not need CAPI-based cluster management support, you can disable CAPI via the Helm Chart values.
Update your Weave GitOps Enterprise HelmRelease object with the global.capiEnabled value set to false:
clusters/management/weave-gitops-enterprise.yaml
---
+apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: HelmRepository
+metadata:
+ name: weave-gitops-enterprise-charts
+ namespace: flux-system
+spec:
+ interval: 60m
+ secretRef:
+ name: weave-gitops-enterprise-credentials
+ url: https://charts.dev.wkp.weave.works/releases/charts-v3
+---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+ name: weave-gitops-enterprise
+ namespace: flux-system
+spec:
+ chart:
+ spec:
+ interval: 65m
+ chart: mccp
+ sourceRef:
+ kind: HelmRepository
+ name: weave-gitops-enterprise-charts
+ namespace: flux-system
+ version: 0.12.0
+ install:
+ crds: CreateReplace
+ upgrade:
+ crds: CreateReplace
+ interval: 50m
+ values:
+ global:
+ capiEnabled: false
+And that's it!
Cluster Management Introduction ENTERPRISE¶
In line with the mantra “cattle, not pets,” Weave GitOps Enterprise (WGE) simplifies managing cluster lifecycle at scale—even massive scale. Through pull requests, which make every action recorded and auditable, WGE makes it possible for teams to create, update, and delete clusters across entire fleets. Breaking things is harder, and recovery is easier. WGE further simplifies the cluster lifecycle management process by providing both a user interface (UI) and a command line interface (CLI) to interact with and manage clusters on-prem, across clouds, and in hybrid environments. You can even use our UI to delete clusters—all it takes is the press of a button that spins up a pull request.
WGE fully supports a range of options, including: - Crossplane integration - Terraform integration, with a Terraform Controller that follows the patterns established by Flux - Cluster API
Helm Charts and Kustomizations Made Easy with Our UI¶
The Weave GitOps Enterprise UI enables you to install software packages to your bootstrapped cluster via the Applications view of our user interface, using a Helm chart (via a HelmRelease) or Kustomization. First, find the "Add an Application" button:
A form will appear, asking you to select the target cluster where you want to add your Application.
Select the source type of either your Git repository or your Helm repository from the selected cluster:
If you select Git repository as the source type, you will be able to add the Application from Kustomization:
If you select Helm repository as the source type, you will be able to add Application from HelmRelease.
And if you choose the profiles Helm chart repository URL, you can select a profile from our Profiles list.
Finally, you can create a pull request to your target cluster and see it on your GitOps repository.
Follow Our User Guide¶
Our user guide provides two pathways to deployment:
Just click the option you want to get started with, and let's go.
import CodeBlock from "@theme/CodeBlock"; import BrowserOnly from "@docusaurus/BrowserOnly";
Managing Clusters Without Cluster API ENTERPRISE¶
You do not need Cluster API to add your Kubernetes cluster to Weave GitOps Enterprise. The only thing you need is a secret containing a valid kubeconfig.
Adding kubeconfig to Your Management Cluster¶
If you already have a kubeconfig stored in a secret in your management cluster, continue with the "Create a GitopsCluster" step below.
If you have a kubeconfig, but it is not yet stored in your management cluster, load it into the cluster using this command:
kubectl create secret generic demo-01-kubeconfig \
+--from-file=value=./demo-01-kubeconfig
+Here's how to create a kubeconfig secret.
apiVersion: v1
+kind: ServiceAccount
+metadata:
+name: demo-01
+namespace: default
+Expand to see role manifests
---
+ apiVersion: rbac.authorization.k8s.io/v1
+ kind: ClusterRoleBinding
+ metadata:
+ name: impersonate-user-groups
+ subjects:
+ - kind: ServiceAccount
+ name: wgesa
+ namespace: default
+ roleRef:
+ kind: ClusterRole
+ name: user-groups-impersonator
+ apiGroup: rbac.authorization.k8s.io
+ ---
+ apiVersion: rbac.authorization.k8s.io/v1
+ kind: ClusterRole
+ metadata:
+ name: user-groups-impersonator
+ rules:
+ - apiGroups: [""]
+ resources: ["users", "groups"]
+ verbs: ["impersonate"]
+ - apiGroups: [""]
+ resources: ["namespaces"]
+ verbs: ["get", "list"]
+This will allow WGE to introspect the cluster for available namespaces.
Once we know what namespaces are available we can test whether the logged in user can access them via impersonation.
kubectl get secrets --field-selector type=kubernetes.io/service-account-token
+ NAME TYPE DATA AGE
+ default-token-lsjz4 kubernetes.io/service-account-token 3 13d
+ demo-01-token-gqz7p kubernetes.io/service-account-token 3 99m
+(demo-01-token-gqz7p is the secret that holds the token for demo-01 service account.)
Then, run the following command to get the service account token:
TOKEN=$(kubectl get secret demo-01-token-gqz7p -o jsonpath={.data.token} | base64 -d)
+Expand to see script
static-kubeconfig.sh
#!/bin/bash
+ if [[ -z "$CLUSTER_NAME" ]]; then
+ echo "Ensure CLUSTER_NAME has been set"
+ exit 1
+ fi
+ if [[ -z "$CA_CERTIFICATE" ]]; then
+ echo "Ensure CA_CERTIFICATE has been set to the path of the CA certificate"
+ exit 1
+ fi
+ if [[ -z "$ENDPOINT" ]]; then
+ echo "Ensure ENDPOINT has been set"
+ exit 1
+ fi
+ if [[ -z "$TOKEN" ]]; then
+ echo "Ensure TOKEN has been set"
+ exit 1
+ fi
+ export CLUSTER_CA_CERTIFICATE=$(cat "$CA_CERTIFICATE" | base64)
+ envsubst <<EOF
+ apiVersion: v1
+ kind: Config
+ clusters:
+ - name: $CLUSTER_NAME
+ cluster:
+ server: https://$ENDPOINT
+ certificate-authority-data: $CLUSTER_CA_CERTIFICATE
+ users:
+ - name: $CLUSTER_NAME
+ user:
+ token: $TOKEN
+ contexts:
+ - name: $CLUSTER_NAME
+ context:
+ cluster: $CLUSTER_NAME
+ user: $CLUSTER_NAME
+ current-context: $CLUSTER_NAME
+ EOF
+You'll need to copy the contents of the certificate into the ca.crt file used below.
CLUSTER_NAME=demo-01 \
+CA_CERTIFICATE=ca.crt \
+ENDPOINT=<control-plane-ip-address> \
+TOKEN=<token> ./static-kubeconfig.sh > demo-01-kubeconfig
+kubectl create secret generic demo-01-kubeconfig \
+--from-file=value=./demo-01-kubeconfig
+Add a Cluster Bootstrap Config¶
This step ensures that Flux gets installed into your cluster. Create a cluster bootstrap config as follows:
kubectl create secret generic my-pat --from-literal GITHUB_TOKEN=$GITHUB_TOKEN
+import CapiGitopsCDC from "!!raw-loader!./assets/bootstrap/capi-gitops-cluster-bootstrap-config.yaml";
Download the config with:
Then update the GITHUB_USER variable to point to your repository
Expand to see full yaml
<CodeBlock title="clusters/management/capi/boostrap/capi-gitops-cluster-bootstrap-config.yaml" className="language-yaml"
{CapiGitopsCDC}
Connect a Cluster¶
To connect your cluster, you need to add some common RBAC rules into the clusters/bases folder. When a cluster is provisioned, by default it will reconcile all the manifests in ./clusters/<cluster-namespace>/<cluster-name> and ./clusters/bases.
To display Applications and Sources in the UI, we need to give the logged-in user the permission to inspect the new cluster. Adding common RBAC rules to ./clusters/bases/rbac is an easy way to configure this.
import WegoAdmin from "!!raw-loader!./assets/rbac/wego-admin.yaml";
Expand to see full template yaml
<CodeBlock title="clusters/bases/rbac/wego-admin.yaml" className="language-yaml"
{WegoAdmin}
Create a GitopsCluster¶
When a GitopsCluster appears in the cluster, the Cluster Bootstrap Controller will install Flux on it and by default start reconciling the ./clusters/demo-01 path in your management cluster's Git repository:
./clusters/management/clusters/demo-01.yaml
apiVersion: gitops.weave.works/v1alpha1
+kind: GitopsCluster
+metadata:
+ name: demo-01
+ namespace: default
+ # Signals that this cluster should be bootstrapped.
+ labels:
+ weave.works/capi: bootstrap
+spec:
+ secretRef:
+ name: demo-01-kubeconfig
+To use the Weave GitOps Enterprise user interface (UI) to inspect the Applications and Sources running on the new cluster, you'll need permissions. We took care of this above when we stored your RBAC rules in ./clusters/bases. In the following step, we'll create a kustomization to add these common resources onto our new cluster:
./clusters/demo-01/clusters-bases-kustomization.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+kind: Kustomization
+metadata:
+ creationTimestamp: null
+ name: clusters-bases-kustomization
+ namespace: flux-system
+spec:
+ interval: 10m0s
+ path: clusters/bases
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: flux-system
+Save these two files in your Git repository, then commit and push.
Once Flux has reconciled the cluster, you can inspect your Flux resources via the UI!
Debugging Tip: Checking that Your kubeconfig Secret Is in Your Cluster¶
To test that your kubeconfig secret is correctly set up, apply the following manifest and check the logs after the job completes:
Expand to see manifest
---
+ apiVersion: batch/v1
+ kind: Job
+ metadata:
+ name: kubectl
+ spec:
+ ttlSecondsAfterFinished: 30
+ template:
+ spec:
+ containers:
+ - name: kubectl
+ image: bitnami/kubectl
+ args:
+ [
+ "get",
+ "pods",
+ "-n",
+ "kube-system",
+ "--kubeconfig",
+ "/etc/kubeconfig/value",
+ ]
+ volumeMounts:
+ - name: kubeconfig
+ mountPath: "/etc/kubeconfig"
+ readOnly: true
+ restartPolicy: Never
+ volumes:
+ - name: kubeconfig
+ secret:
+ secretName: demo-01-kubeconfig
+ optional: false
+In the manifest above, demo-01-kubeconfig is the name of the secret that contains the kubeconfig for the remote cluster.
Additional Resources¶
Other documentation that you might find useful:
Profiles ENTERPRISE¶
BEFORE YOU START
The following instructions require you to make minor changes to the content of your own hosted Helm repository.
To put it simply, Profiles are Helm charts. To create a Profile, you need to add an annotation to a Helm chart.
A very simple Helm chart marked up as a Profile looks like this:
name: demo-profile
+version: 0.0.1
+annotations:
+ weave.works/profile: "A Demo Profile"
+Mark a HelmRepository as Containing Profiles¶
Alternatively, you can annotate a Flux HelmRepository
apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: HelmRepository
+metadata:
+ name: podinfo
+ namespace: default
+ annotations:
+ weave.works/profiles: "true" # this identifies all charts as profiles
+spec:
+ interval: 5m0s
+ url: https://stefanprodan.github.io/podinfo
+This will ensure that all charts in the HelmRepository are identified as Profiles.
Add Layers to Define Dependencies Between Your Profiles¶
Profile layers are a mechanism for loosely defining dependencies between Profiles.
To add a layer to a Profile chart:
name: demo-profile
+version: 0.0.1
+annotations:
+ weave.works/profile: "A Demo Profile"
+ weave.works/layer: "demo"
+When multiple Profiles are specified in an API call, with layers in the API request then the set of layers is sorted, reversed, and configured as dependencies using Flux's dependsOn mechanism.
┌─────────┐ ┌─────────┐ ┌─────────┐
+│ │ │ │ │ │
+│ layer-3 ├──────► layer-2 ├──────► layer-1 │
+│ │ │ │ │ │
+└─────────┘ └─────────┘ └─────────┘
+ dependsOn dependsOn
+The scope of the dependsOn calculation is limited to the set of Profiles in the API call.
If only one chart is being installed, no dependsOn is configured.
If several charts are installed in the same layer, then the preceeding layer charts will be configured to depend on all the charts in the succeeding layer.
┌──────────┐ ┌─────────┐ ┌─────────┐
+│ │ │ │ │ │
+│ layer-3 ├─────► layer-2 ├──────► layer-1 │
+│ │ │ │ │ │
+└──────────┤ └─────────┘ └─▲───────┘
+ dependsOn │ dependsOn │
+ │ │
+ │ ┌─────────┐ │
+ │ │ │ │
+ └─────► layer-2 ├────────┘
+ │ │
+ └─────────┘
+ dependsOn
+dependsOn for the chart without a layer to depend on the chart with layer. (Optional) Use a Helm Chart from a Remote Public/Private Repository¶
You can add your Profiles to a remote repository that can be referenced using a HelmRepository resource. The repository can be either public or private. Using a private repo requires a few extra steps.
In this example, a public repo and branch is referenced directly where the Helm releases are:
HelmRepository.yaml
apiVersion: source.toolkit.fluxcd.io/v1beta1
+kind: HelmRepository
+metadata:
+ name: weaveworks-charts
+ namespace: flux-system
+spec:
+ interval: 1m
+ url: https://weaveworks.github.io/weave-gitops-profile-examples/
+To use private repositories with restricted access, you can use a secret synced to the target leaf cluster. SecretSync references the secret as spec.secretRef. The labels of your target leaf cluster are added for the syncer to match clusters against those labels using spec.clusterSelector.matchLabels.
SecretSync.yaml
apiVersion: capi.weave.works/v1alpha1
+kind: SecretSync
+metadata:
+ name: my-dev-secret-syncer
+ namespace: flux-system
+spec:
+ clusterSelector:
+ matchLabels:
+ weave.works/capi: bootstrap
+ secretRef:
+ name: weave-gitops-enterprise-credentials
+ targetNamespace: flux-system
+Once the SecretSync and Secret are available, the secret can be directly referenced in the HelmRepository object:
PrivateHelmRepository.yaml
apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: HelmRepository
+metadata:
+ name: weaveworks-charts
+ namespace: flux-system
+spec:
+ interval: 60m
+ secretRef:
+ name: weave-gitops-enterprise-credentials
+ url: https://charts.dev.wkp.weave.works/releases/charts-v3
+Note: The HelmRepoSecret, SecretSync, and the GitopsCluster should all be in the same namespace.
Select the Profiles You Want Installed at Cluster Creation¶
WGE inspects the namespace in the management cluster where it is deployed, and looks for a HelmRepository object named weaveworks-charts. This Kubernetes object should point to a Helm chart repository that includes the Profiles available for installation.
When creating a cluster from the UI using a CAPI template, these Profiles are available for selection in the Profiles section of the template. For example:
As shown above, some Profiles are optional, while others are required. This is determined when the template is authored and allows for operations teams to control which Helm packages should be installed on new clusters by default.
To enable editing of the yaml values for required Profiles, add the editable flag in the annotation and describe the required Profile in the template. For example:
apiVersion: templates.weave.works/v1alpha2
+kind: GitOpsTemplate
+metadata:
+ name: connect-a-cluster-with-policies
+ namespace: default
+ annotations:
+ capi.weave.works/profile-0: '{"name": "weave-policy-agent", "editable": true, "version": "0.2.8", "values": "accountId: weaveworks\nclusterId: ${CLUSTER_NAME}" }'
+Weave GitOps Enterprise ENTERPRISE¶
Ready for more GitOps?
To purchase an entitlement to Weave GitOps Enterprise, please contact sales@weave.works.
Weave GitOps Enterprise provides ops teams with an easy way to assess the health of multiple clusters in a single place. It shows cluster information such as Kubernetes version and number of nodes and provides details about the GitOps operations on those clusters, such as Git repositories and recent commits. Additionally, it aggregates Prometheus alerts to assist with troubleshooting.
If you have already purchased your entitlement, head to the installation page.
Feature Breakdown¶
In addition to the features in the OSS edition, Weave GitOps Enterprise offers the following capabilities, taking your delivery from simple Continuous Delivery to Internal Developer Platform:
Cluster Fleet Management¶
Weave GitOps Enterprise (WGE) simplifies cluster lifecycle management at scale—even massive scale. Through pull requests, which make every action recorded and auditable, WGE makes it possible for teams to create, update, and delete clusters across entire fleets. WGE further simplifies the process by providing both a user interface (UI) and a command line interface (CLI) for teams to interact with and manage clusters on-prem, across clouds, and in hybrid environments. WGE works with Terraform, Crossplane, and any Cluster API provider.
Trusted Application Delivery¶
Add policy as code to GitOps pipelines and enforce security and compliance, application resilience and coding standards from source to production. Validate policy conformance at every step in the software delivery pipeline: commit, build, deploy and run time.
Progressive Delivery¶
Deploy into production environments safely using canary, blue/green deployment, and A/B strategies. Simple, single-file configuration defines success rollback. Measure Service Level Objectives (SLOs) using observability metrics from Prometheus, Datadog, New Relic, and others.
CD Pipelines¶
Rollout new software from development to production. Environment rollouts that work with your existing CI system.
Team Workspaces¶
Allow DevOps teams to work seamlessly together with multi-tenancy, total RBAC control, and policy enforcement, with integration to enterprise IAM.
Self-Service Templates and Profiles¶
Component profiles enable teams to deploy standard services quickly, consistently and reliably. Teams can curate the profiles that are available within their estate ensuring there is consistency everywhere. Using GitOps it's easy to guarantee the latest, secure versions of any component are deployed in all production systems.
Health Status and Compliance Dashboards¶
Gain a single view of the health and state of the cluster and its workloads. Monitor deployments and alert on policy violations across apps and clusters.
Kubernetes Anywhere¶
Reduce complexity with GitOps and install across all major target environments including support for on-premise, edge, hybrid, and multi-cloud Kubernetes clusters.
Critical 24/7 Support¶
Your business and workloads operate around the clock, and so do we. Whenever you have a problem, our experts are there to help. We’ve got your back!
Install Enterprise in Air-gapped Environments ENTERPRISE¶
From wikipedia
An air gap, air wall, air gapping or disconnected network is a network security measure employed on one or more computers to ensure that a secure computer network is physically isolated from unsecured networks, such as the public Internet or an unsecured local area network...
This document guides on how to install Weave GitOps Enterprise (WGE) in a restricted environment.
Before You Start¶
There are multiple restrictions that could happen within an air-gapped environment. This guide assumes that you have egress network restrictions. In order to install WGE, the required artifacts must be loaded from a private registry. This guide helps you with the task to identity the Helm charts and container images required to install WGE and to load them into your private registry.
It also assumes that you could prepare the installation from a proxy host. A proxy host is defined here as a computer that is able to access to both the public and private network. It could take different shapes, for example, it could be a bastion host, a corp laptop, etc.
Access to both public and private network is required during the airgap installation but not simultaneously. It is expected to have an online stage to gather the artifacts first, and an offline stage later, to load the artifacts in the private network.
Finally, we aim to provide an end to end example to use it as a guidance more than a recipe. Feel free to adapt the details that do not fit within your context.
Install WGE¶
There are different variations of the following stages and conditions. We consider that installing WGE in an air-gapped environment could follow the following stages.
Set up a WGE install environment¶
The main goal of this stage is to recreate a local WGE within your context, to collect the container images and Helm charts, that will be required in your private registry for the offline installation.
A three-step setup is followed.
Setup a proxy host¶
There are many possible configurations for this host. This guide will assume that the host has installed the following:
Create a Kind Cluster¶
Create a kind cluster with registry following this guide
Install Flux¶
You could just use flux install to install Flux into your kind cluster
Set up a Helm repo¶
We are going to install ChartMuseum via Flux.
Remember to also install helm plugin cm-push.
Expand to see installation yaml
---
+apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: HelmRepository
+metadata:
+name: chartmuseum
+namespace: flux-system
+spec:
+interval: 10m
+url: https://chartmuseum.github.io/charts
+---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+name: chartmuseum
+namespace: flux-system
+spec:
+chart:
+ spec:
+ chart: chartmuseum
+ sourceRef:
+ kind: HelmRepository
+ name: chartmuseum
+ namespace: flux-system
+interval: 10m0s
+timeout: 10m0s
+releaseName: helm-repo
+install:
+ crds: CreateReplace
+ remediation:
+ retries: 3
+values:
+ env:
+ open:
+ DISABLE_API: "false"
+ AUTH_ANONYMOUS_GET: "true"
+Set up access from your host.
#expose kubernetes svc
+kubectl -n flux-system port-forward svc/helm-repo-chartmuseum 8080:8080 &
+
+#add hostname
+sudo -- sh -c "echo 127.0.0.1 helm-repo-chartmuseum >> /etc/hosts"
+#add repo to helm
+helm repo add private http://helm-repo-chartmuseum:8080
+
+#test that works
+helm repo update private
+At this stage you have already a private registry for container images and helm charts.
Install WGE¶
This step is to gather the artifacts and images in your local environment to push to the private registry.
Cluster API¶
This would vary depending on the provider, given that we target a offline environment, most likely we are in a private cloud environment, so we will be using liquidmetal.
Export these environment variables to configure your CAPI experience. Adjust them to your context.
export CAPI_BASE_PATH=/tmp/capi
+export CERT_MANAGER_VERSION=v1.9.1
+export CAPI_VERSION=v1.3.0
+export CAPMVM_VERSION=v0.7.0
+export EXP_CLUSTER_RESOURCE_SET=true
+export CONTROL_PLANE_MACHINE_COUNT=1
+export WORKER_MACHINE_COUNT=1
+export CONTROL_PLANE_VIP="192.168.100.9"
+export HOST_ENDPOINT="192.168.1.130:9090"
+Execute the following script to generate clusterctl config file.
cat << EOF > clusterctl.yaml
+cert-manager:
+ url: "$CAPI_BASE_PATH/cert-manager/$CERT_MANAGER_VERSION/cert-manager.yaml"
+
+providers:
+ - name: "microvm"
+ url: "$CAPI_BASE_PATH/infrastructure-microvm/$CAPMVM_VERSION/infrastructure-components.yaml"
+ type: "InfrastructureProvider"
+ - name: "cluster-api"
+ url: "$CAPI_BASE_PATH/cluster-api/$CAPI_VERSION/core-components.yaml"
+ type: "CoreProvider"
+ - name: "kubeadm"
+ url: "$CAPI_BASE_PATH/bootstrap-kubeadm/$CAPI_VERSION/bootstrap-components.yaml"
+ type: "BootstrapProvider"
+ - name: "kubeadm"
+ url: "$CAPI_BASE_PATH/control-plane-kubeadm/$CAPI_VERSION/control-plane-components.yaml"
+ type: "ControlPlaneProvider"
+EOF
+make using the following makefile to intialise CAPI in your cluster: Expand to see Makefile contents
.PHONY := capi
+
+capi: capi-init capi-cluster
+
+capi-init: cert-manager cluster-api bootstrap-kubeadm control-plane-kubeadm microvm clusterctl-init
+
+cert-manager:
+ mkdir -p $(CAPI_BASE_PATH)/cert-manager/$(CERT_MANAGER_VERSION)
+ curl -L https://github.com/cert-manager/cert-manager/releases/download/$(CERT_MANAGER_VERSION)/cert-manager.yaml --output $(CAPI_BASE_PATH)/cert-manager/$(CERT_MANAGER_VERSION)/cert-manager.yaml
+
+cluster-api:
+ mkdir -p $(CAPI_BASE_PATH)/cluster-api/$(CAPI_VERSION)
+ curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/$(CAPI_VERSION)/core-components.yaml --output $(CAPI_BASE_PATH)/cluster-api/$(CAPI_VERSION)/core-components.yaml
+ curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/$(CAPI_VERSION)/metadata.yaml --output $(CAPI_BASE_PATH)/cluster-api/$(CAPI_VERSION)/metadata.yaml
+
+bootstrap-kubeadm:
+ mkdir -p $(CAPI_BASE_PATH)/bootstrap-kubeadm/$(CAPI_VERSION)
+ curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/$(CAPI_VERSION)/bootstrap-components.yaml --output $(CAPI_BASE_PATH)/bootstrap-kubeadm/$(CAPI_VERSION)/bootstrap-components.yaml
+ curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/$(CAPI_VERSION)/metadata.yaml --output $(CAPI_BASE_PATH)/bootstrap-kubeadm/$(CAPI_VERSION)/metadata.yaml
+
+control-plane-kubeadm:
+ mkdir -p $(CAPI_BASE_PATH)/control-plane-kubeadm/$(CAPI_VERSION)
+ curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/$(CAPI_VERSION)/control-plane-components.yaml --output $(CAPI_BASE_PATH)/control-plane-kubeadm/$(CAPI_VERSION)/control-plane-components.yaml
+ curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/$(CAPI_VERSION)/metadata.yaml --output $(CAPI_BASE_PATH)/control-plane-kubeadm/$(CAPI_VERSION)/metadata.yaml
+
+microvm:
+ mkdir -p $(CAPI_BASE_PATH)/infrastructure-microvm/$(CAPMVM_VERSION)
+ curl -L https://github.com/weaveworks-liquidmetal/cluster-api-provider-microvm/releases/download/$(CAPMVM_VERSION)/infrastructure-components.yaml --output $(CAPI_BASE_PATH)/infrastructure-microvm/$(CAPMVM_VERSION)/infrastructure-components.yaml
+ curl -L https://github.com/weaveworks-liquidmetal/cluster-api-provider-microvm/releases/download/$(CAPMVM_VERSION)/cluster-template-cilium.yaml --output $(CAPI_BASE_PATH)/infrastructure-microvm/$(CAPMVM_VERSION)/cluster-template-cilium.yaml
+ curl -L https://github.com/weaveworks-liquidmetal/cluster-api-provider-microvm/releases/download/$(CAPMVM_VERSION)/metadata.yaml --output $(CAPI_BASE_PATH)/infrastructure-microvm/$(CAPMVM_VERSION)/metadata.yaml
+
+clusterctl-init:
+ clusterctl init --wait-providers -v 4 --config clusterctl.yaml --infrastructure microvm
+
+capi-cluster:
+ clusterctl generate cluster --config clusterctl.yaml -i microvm:$(CAPMVM_VERSION) -f cilium lm-demo | kubectl apply -f -
+Deploying the Terraform Controller¶
Apply the following example manifest to deploy the Terraform Controller:
Expand to see file contents
apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: HelmRepository
+metadata:
+name: tf-controller
+namespace: flux-system
+spec:
+interval: 10m
+url: https://weaveworks.github.io/tf-controller/
+---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+name: tf-controller
+namespace: flux-system
+spec:
+chart:
+ spec:
+ chart: tf-controller
+ version: "0.9.2"
+ sourceRef:
+ kind: HelmRepository
+ name: tf-controller
+ namespace: flux-system
+interval: 10m0s
+install:
+ crds: CreateReplace
+ remediation:
+ retries: 3
+upgrade:
+ crds: CreateReplace
+WGE¶
Update the following manifest to your context.
Expand to see file contents
---
+apiVersion: v1
+data:
+deploy-key: <changeme>
+entitlement: <changeme>
+password: <changeme>
+username: <changeme>
+kind: Secret
+metadata:
+labels:
+ kustomize.toolkit.fluxcd.io/name: shared-secrets
+ kustomize.toolkit.fluxcd.io/namespace: flux-system
+name: weave-gitops-enterprise-credentials
+namespace: flux-system
+type: Opaque
+---
+apiVersion: v1
+data:
+password: <changeme>
+username: <changeme>
+kind: Secret
+metadata:
+labels:
+ kustomize.toolkit.fluxcd.io/name: enterprise
+ kustomize.toolkit.fluxcd.io/namespace: flux-system
+name: cluster-user-auth
+namespace: flux-system
+type: Opaque
+---
+apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: HelmRepository
+metadata:
+name: weave-gitops-enterprise-charts
+namespace: flux-system
+spec:
+interval: 10m
+secretRef:
+ name: weave-gitops-enterprise-credentials
+url: https://charts.dev.wkp.weave.works/releases/charts-v3
+---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+name: weave-gitops-enterprise
+namespace: flux-system
+spec:
+chart:
+ spec:
+ chart: mccp
+ version: "0.10.2"
+ sourceRef:
+ kind: HelmRepository
+ name: weave-gitops-enterprise-charts
+ namespace: flux-system
+interval: 10m0s
+install:
+ crds: CreateReplace
+ remediation:
+ retries: 3
+upgrade:
+ crds: CreateReplace
+values:
+ global:
+ capiEnabled: true
+ enablePipelines: true
+ enableTerraformUI: true
+ clusterBootstrapController:
+ enabled: true
+ cluster-controller:
+ controllerManager:
+ kubeRbacProxy:
+ image:
+ repository: gcr.io/kubebuilder/kube-rbac-proxy
+ tag: v0.8.0
+ manager:
+ image:
+ repository: docker.io/weaveworks/cluster-controller
+ tag: v1.4.1
+ policy-agent:
+ enabled: true
+ image: weaveworks/policy-agent
+ pipeline-controller:
+ controller:
+ manager:
+ image:
+ repository: ghcr.io/weaveworks/pipeline-controller
+ images:
+ clustersService: docker.io/weaveworks/weave-gitops-enterprise-clusters-service:v0.10.2
+ uiServer: docker.io/weaveworks/weave-gitops-enterprise-ui-server:v0.10.2
+ clusterBootstrapController: weaveworks/cluster-bootstrap-controller:v0.4.0
+At this stage you should have a local management cluster with Weave GitOps Enterprise installed.
➜ kubectl get pods -A
+NAMESPACE NAME READY STATUS RESTARTS AGE
+...
+flux-system weave-gitops-enterprise-cluster-controller-6f8c69dc8-tq994 2/2 Running 5 (12h ago) 13h
+flux-system weave-gitops-enterprise-mccp-cluster-bootstrap-controller-cxd9c 2/2 Running 0 13h
+flux-system weave-gitops-enterprise-mccp-cluster-service-8485f5f956-pdtxw 1/1 Running 0 12h
+flux-system weave-gitops-enterprise-pipeline-controller-85b76d95bd-2sw7v 1/1 Running 0 13h
+...
+You can observe the installed Helm Charts with kubectl:
kubectl get helmcharts.source.toolkit.fluxcd.io
+NAME CHART VERSION SOURCE KIND SOURCE NAME AGE READY STATUS
+flux-system-cert-manager cert-manager 0.0.7 HelmRepository weaveworks-charts 13h True pulled 'cert-manager' chart with version '0.0.7'
+flux-system-tf-controller tf-controller 0.9.2 HelmRepository tf-controller 13h True pulled 'tf-controller' chart with version '0.9.2'
+flux-system-weave-gitops-enterprise mccp v0.10.2 HelmRepository weave-gitops-enterprise-charts 13h True pulled 'mccp' chart with version '0.10.2'
+As well as the container images:
kubectl get pods --all-namespaces -o jsonpath="{.items[*].spec['containers','initContainers'][*].image}" |tr -s '[[:space:]]' '\n' \
+| sort | uniq | grep -vE 'kindest|etcd|coredns'
+
+docker.io/prom/prometheus:v2.34.0
+docker.io/weaveworks/cluster-controller:v1.4.1
+docker.io/weaveworks/weave-gitops-enterprise-clusters-service:v0.10.2
+docker.io/weaveworks/weave-gitops-enterprise-ui-server:v0.10.2
+ghcr.io/fluxcd/flagger-loadtester:0.22.0
+ghcr.io/fluxcd/flagger:1.21.0
+ghcr.io/fluxcd/helm-controller:v0.23.1
+ghcr.io/fluxcd/kustomize-controller:v0.27.1
+ghcr.io/fluxcd/notification-controller:v0.25.2
+...
+Collect and Publish Artifacts¶
This section guides you to push installed artifacts to your private registry. Here's a Makefile to help you with each stage:
Expand to see Makefile contents
.PHONY := all
+
+ #set these variable with your custom configuration
+ PRIVATE_HELM_REPO_NAME=private
+ REGISTRY=localhost:5001
+ WGE_VERSION=0.10.2
+
+ WGE=mccp-$(WGE_VERSION)
+ WGE_CHART=$(WGE).tgz
+
+ all: images charts
+
+ charts: pull-charts push-charts
+
+ images:
+ kubectl get pods --all-namespaces -o jsonpath="{.items[*].spec['containers','initContainers'][*].image}" \
+ |tr -s '[[:space:]]' '\n' | sort | uniq | grep -vE 'kindest|kube-(.*)|etcd|coredns' | xargs -L 1 -I {} ./image-sync.sh {} $(REGISTRY)
+ kubectl get microvmmachinetemplates --all-namespaces -o jsonpath="{.items[*].spec.template.spec.kernel.image}"|tr -s '[[:space:]]' '\n' \
+ | sort | uniq | xargs -L 1 -I {} ./image-sync.sh {} $(REGISTRY)
+
+ pull-charts:
+ curl -L https://s3.us-east-1.amazonaws.com/weaveworks-wkp/releases/charts-v3/$(WGE_CHART) --output $(WGE_CHART)
+
+ push-charts:
+ helm cm-push -f $(WGE_CHART) $(PRIVATE_HELM_REPO_NAME)
+The image-sync.sh referenced in the images target of the the above Makefile is similar to:
skopeo copy docker://$1 docker://$2/$1 --preserve-digests --multi-arch=all
+Skopeo allows you to configure a range a security features to meet your requirements. For example, configuring trust policies before pulling or signing containers before making them available in your private network. Feel free to adapt the previous script to meet your security needs.
➜ resources git:(docs-airgap-install) ✗ make
+kubectl get microvmmachinetemplates --all-namespaces -o jsonpath="{.items[*].spec.template.spec.kernel.image}"|tr -s '[[:space:]]' '\n' \
+ | sort | uniq | xargs -L 1 -I {} ./image-pull-push.sh {} docker-registry:5000
+
+5.10.77: Pulling from weaveworks-liquidmetal/flintlock-kernel
+Digest: sha256:5ef5f3f5b42a75fdb69cdd8d65f5929430f086621e61f00694f53fe351b5d466
+Status: Image is up to date for ghcr.io/weaveworks-liquidmetal/flintlock-kernel:5.10.77
+ghcr.io/weaveworks-liquidmetal/flintlock-kernel:5.10.77
+...5.10.77: digest: sha256:5ef5f3f5b42a75fdb69cdd8d65f5929430f086621e61f00694f53fe351b5d466 size: 739
+Airgap Install¶
Weave GitOps Enterprise¶
At this stage you have in your private registry both the Helm charts and container images required to install Weave GitOps Enterprise. Now you are ready to install WGE from your private registry.
Follow the instructions to install WGE with the following considerations:
An example of how it would look for Weave GitOps Enterprise is shown below.
Expand to view example WGE manifest
weave-gitops-enterprise.yaml
---
+apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: HelmRepository
+metadata:
+name: weave-gitops-enterprise-charts
+namespace: flux-system
+spec:
+interval: 1m
+url: http://helm-repo-chartmuseum:8080
+---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+name: weave-gitops-enterprise
+namespace: flux-system
+spec:
+chart:
+ spec:
+ chart: mccp
+ version: "0.10.2"
+ sourceRef:
+ kind: HelmRepository
+ name: weave-gitops-enterprise-charts
+ namespace: flux-system
+interval: 1m0s
+install:
+ crds: CreateReplace
+ remediation:
+ retries: 3
+upgrade:
+ crds: CreateReplace
+values:
+ global:
+ capiEnabled: true
+ enablePipelines: true
+ enableTerraformUI: true
+ clusterBootstrapController:
+ enabled: true
+ #images changed
+ cluster-controller:
+ controllerManager:
+ kubeRbacProxy:
+ image:
+ repository: localhost:5001/gcr.io/kubebuilder/kube-rbac-proxy
+ tag: v0.8.0
+ manager:
+ image:
+ repository: localhost:5001/docker.io/weaveworks/cluster-controller
+ tag: v1.4.1
+ policy-agent:
+ enabled: true
+ image: localhost:5001/weaveworks/policy-agent
+ pipeline-controller:
+ controller:
+ manager:
+ image:
+ repository: localhost:5001/ghcr.io/weaveworks/pipeline-controller
+ images:
+ clustersService: localhost:5001/docker.io/weaveworks/weave-gitops-enterprise-clusters-service:v0.10.2
+ uiServer: localhost:5001/docker.io/weaveworks/weave-gitops-enterprise-ui-server:v0.10.2
+ clusterBootstrapController: localhost:5001/weaveworks/cluster-bootstrap-controller:v0.4.0
+Cluster API¶
Indicate in the Cluster API configuration file clusterctl.yaml that you want to use images from the private repo by leveraging image overrides.
images:
+ all:
+ repository: localhost:5001/registry.k8s.io/cluster-api
+ infrastructure-microvm:
+ repository: localhost:5001/ghcr.io/weaveworks-liquidmetal
+make clusterctl-init to init capi using your private registry. Azure and Weave GitOps Enterprise Installation ENTERPRISE¶
Once you successfully create your Kubernetes cluster in Azure Marketplace, follow these steps to Install Weave GitOps Enterprise. These instructions apply to both Azure AKS and Azure ARC clusters—they'll behave in the same way.
Tip
If you have already installed Flux, then Azure Flux will refuse to install.
1. Choose the “GitOps” Option in the Marketplace¶
Search for Weave GitOps Enterprise in the "Extensions + Applications" of the Azure Marketplace. Click the "GitOps" option. This will take you to a screen that presents a first-class item called Type: Flux v2.
Click GitOps => Create.
Add the config name, namespace (default), scope: cluster, type (Flux v2), and continuous reconciliation option. Your entries should look like this:
All of the displayed properties for the Flux objects screen are the same as what you'd supply to Flux bootstrap.
Optional: Install CAPZ, the CAPI Provider¶
If you are planning to manage or connect CAPI clusters to the WE service make sure you first install the CAPI provider. Then during the WE installation process be sure to select the "Enable CAPI support" checkbox.
2. Apply the Entitlements Secret¶
Contact sales@weave.works for a valid entitlements secret. This will come in the form of a file “entitlements.yaml”. Apply it to the cluster:
kubectl apply -f entitlements.yaml
+3. Configure Access for Writing to Git from the UI¶
(This section is the same as what you'll find in the main WGE install documentation.)
Here we provide guidance for GitHub, GitLab, BitBucket Server, and Azure DevOps.
Create a GitLab OAuth application that will request api permissions to create pull requests on your behalf.
Follow the GitLab docs.
The application should have at least these scopes:
Add callback URLs to the application for each address the UI will be exposed on, e.g.:
Save your application, taking note of the Client ID and Client Secret. Save them into the git-provider-credentials secret, along with:
Replace values in this snippet and run:
kubectl create secret generic git-provider-credentials --namespace=flux-system \
+ --from-literal="GITLAB_CLIENT_ID=13457" \
+ --from-literal="GITLAB_CLIENT_SECRET=24680" \
+ --from-literal="GITLAB_HOSTNAME=git.example.com" \
+ --from-literal="GIT_HOST_TYPES=git.example.com=gitlab"
+
Create a new incoming application link from the BitBucket administration dashboard. You will be asked to enter a unique name and the redirect URL for the external application. The redirect URL should be set to <WGE dashboard URL>/oauth/bitbucketserver. You will also need to select permissions for the application. The minimum set of permissions needed for WGE to create pull requests on behalf of users is Repositories - Write. An example of configuring these settings is shown below.
Save your application and take note of the Client ID and Client Secret. Save them into the git-provider-credentials secret, along with:
Replace values in this snippet and run:
kubectl create secret generic git-provider-credentials --namespace=flux-system \
+ --from-literal="BITBUCKET_SERVER_CLIENT_ID=13457" \
+ --from-literal="BITBUCKET_SERVER_CLIENT_SECRET=24680" \
+ --from-literal="BITBUCKET_SERVER_HOSTNAME=git.example.com" \
+ --from-literal="GIT_HOST_TYPES=git.example.com=bitbucket-server"
+If the secret is already present, use the following command to update it using your default editor:
kubectl edit secret generic git-provider-credentials --namespace=flux-system
+Info
If BitBucket Server is running on the default port (7990), make sure you include the port number in the values of the secret. For example: GIT_HOST_TYPES=git.example.com:7990=bitbucket-server
Navigate to VisualStudio and register a new application, as explained in the docs. Set the authorization callback URL and select which scopes to grant. Set the callback URL to <WGE dashboard URL>/oauth/azuredevops.
Select the Code (read and write) scope from the list. This is necessary so that WGE can create pull requests on behalf of users. An example of configuring these settings is shown below.
After creating your application, you will be presented with the application settings. Take note of the App ID and Client Secret values—you will use them to configure WGE.
In your cluster, create a secret named git-provider-credentials that contains the App ID and Client Secret values from the newly created application.
Replace values in this snippet and run:
kubectl create secret generic git-provider-credentials --namespace=flux-system \
+ --from-literal="AZURE_DEVOPS_CLIENT_ID=<App ID value>" \
+ --from-literal="AZURE_DEVOPS_CLIENT_SECRET=<Client Secret value>"
+WGE is now configured to ask users for authorization the next time a pull request must be created as part of using a template. Note that each user can view and manage which applications they have authorized by navigating to https://app.vsaex.visualstudio.com/me.
4. Configure Your Password¶
First, install the Weave GitOps Enterprise CLI tool. To do this, you can use either brew or curl.
brew install weaveworks/tap/gitops-ee
+curl --silent --location "https://artifacts.wge.dev.weave.works/releases/bin/0.27.0/gitops-$(uname)-$(uname -m).tar.gz" | tar xz -C /tmp
+sudo mv /tmp/gitops /usr/local/bin
+gitops version
+
Now, to login to the WGE UI, generate a bcrypt hash for your chosen password and store it as a secret in the Kubernetes cluster. There are several different ways to generate a bcrypt hash. Here, we'll use gitops get bcrypt-hash from our GitOps CLI.
PASSWORD="<Make up and insert a brand-new password here>"
+echo -n $PASSWORD | gitops get bcrypt-hash | kubectl create secret generic cluster-user-auth -n flux-system --from-literal=username=wego-admin --from-file=password=/dev/stdin
+A validation to know it’s working:
kubectl get secret -n flux-system cluster-user-auth
+5. Install Weave GitOps Enterprise to Your Cluster¶
First, you'll get taken to the Weaveworks portal on the Azure platform, which provides your subscription details.
Search for Weave GitOps. Pick "View private products" and choose WGE. Fill out the forms, selecting your cluster, then choose "Review and Create".
6. Apply Extra Configuration¶
Additional configuration is done through an optional ConfigMap:
apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: cluster-service-extra-config
+ namespace: flux-system
+data:
+ # disable TLS
+NO_TLS: "true"
+Apply the configuration with:
kubectl apply -f cluster-service-extra-config.yaml
+
+# restart the clusters-service for changes to take effect
+kubectl -n flux-system rollout restart deploy/weave-gitops-enterprise-mccp-cluster-service
+Available Configuration Options¶
| value | default | description |
|---|---|---|
NO_TLS | "false" | disable TLS |
CLUSTER_NAME | "management" | name of the management cluster |
AUTH_METHODS | "token-passthrough,user-account" | Which auth methods to use, valid values are 'oidc', 'token-pass-through' and 'user-account' |
OIDC_ISSUER_URL | "token-passthrough,user-account" | The URL of the OpenID Connect issuer |
OIDC_CLIENT_ID | "token-passthrough,user-account" | The client ID for the OpenID Connect client |
OIDC_CLIENT_SECRET | "token-passthrough,user-account" | The client secret to use with OpenID Connect issuer |
OIDC_REDIRECT_URL | "token-passthrough,user-account" | The OAuth2 redirect URL |
OIDC_TOKEN_DURATION | "1h" | The duration of the ID token. It should be set in the format: number + time unit (s,m,h) e.g., 20m |
OIDC_CLAIM_USERNAME | "email" | JWT claim to use as the user name. By default email, which is expected to be a unique identifier of the end user. Admins can choose other claims, such as sub or name, depending on their provider |
OIDC_CLAIM_GROUPS | "groups" | JWT claim to use as the user's group. If the claim is present it must be an array of strings |
CUSTOM_OIDC_SCOPES | "groups, openid, email, profile" | Customise the requested scopes for then OIDC authentication flow - openid will always be requested |
7. Check That It Works¶
Go to the "services and ingresses" tab in the Azure portal and look for signs that the UI installed.
Troubleshooting¶
WGE will try and automatically install Flux on a new cluster. If this fails for some reason, or if you need a custom Flux installation, you can manually install it before installing WGE.
Click "Next" and add:
And under the "Authentication" section:
Click "Next". You'll see an option to create a Kustomisation, which is optional. To create one:
Click "Save". Then clicking "Next", which will give you a summary so you can review your input. Then click "Create". It will take about five minutes to deploy.
You'll get to a new screen, which at the top-right shows "Notifications" and will display creation of the Flux configuration. When your deployment succeeds, go to the resource and pin to your dashboard. Then go to your terminal to see if it works in kubectl. In the terminal you'll get the GitRepository and Kustomizations. You should then get a green "succeeded" checkmark.
The Kustomisations screen does not provide an option to inspect the path/target namespace—you have to supply the target Namespace in the Kustomization object.
Next Steps¶
From this point, you can follow our generalized WGE installation instructions to configure TLS and log into the UI. Installing the Azure Marketplace product installs the Helm chart.
Install Weave GitOps Enterprise via CLI¶
Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
You could install Weave GitOps Enterprise via gitops-ee bootstrap CLI command which is suitable for two main scenarios:
Each scenario is supported by an operation modes:
For those seeking other scenarios or fine-grain customisation Weave GitOps Enterprise manual install would be the recommended.
Getting Started¶
Prerequisites¶
Before you start make sure the following requirements are met:
Install gitops-ee CLI (> v0.35)¶
Weave GitOps Enterprise Bootstrap functionality is available on Weave GitOps Enterprise CLI starting from version v0.35. If you haven't already, please install the latest gitops-ee CLI using this command.
brew install weaveworks/tap/gitops-ee
+Bootstrap Weave GitOps Enterprise¶
Please use the following command to start the installation wizard of Weave GitOps Enterprise.
gitops bootstrap
+You could run the bootstrap command in non-interactive mode by providing the required configurations as flags. The following gives you an example to get started that you could adapt to your own context
gitops bootstrap \
+ --kubeconfig=$HOME/.kube/config \
+ --private-key=$HOME/.ssh/id_rsa --private-key-password="" \
+ --version="0.35.0" \
+ --domain-type="localhost" \
+ --password="admin123"
+For more information about the CLI configurations, check the below sections here
Appendix¶
Understanding gitops-ee bootstrap¶
gitops-ee bootstrap is a workflow that will take you through the following stages:
Verify Flux¶
Weave GitOps Enterprise runs on top of flux, the bootstrap CLI will check if flux is installed on the management cluster, and it will verify that it has the right version with valid git repository setup, and it is able to reconcile flux components properly. If flux is installed, but doesn't have a valid installation, the bootstrap CLI will terminate pending the fix or uninstall of current flux installation.
Verify Entitlement¶
Weave GitOps Enterprise Entitlement is your obtained license to use our product. The Entitlements file is a Kubernetes secret that contains your licence. Bootstrapping checks that the secret exists on the management cluster, and that it is valid will check if it has valid content and the entitlement is not expired. To get the entitlement secret please contact sales@weave.works, then apply it on your management cluster with the name weave-gitops-enterprise-credentials under flux-system namespace.
Configure Git Access¶
In order for gitops-ee bootstrap to push WGE resources to the management cluster's git repository, you will be prompted to provide the private key used to access your repo via ssh. If the private key is encrypted, you will also be asked to provide the private key password.
Info
Disclaimer: The bootstrap CLI will ONLY use the private key to push WGE resources to your repo, and won't use it in any other way that can comprimise your repo or clusters security.
Select WGE version¶
The bootstrap CLI will prompt you to choose from the latest 3 versions of Weave GitOps Enterprise.
Create Cluster User¶
You will be prompt to provide admin username and password, which will be used to access the dashboard. This will create admin secret with the credentials. If you already have previous admin credentials on your cluster, the installation will prompt you if you want to continue with the old credentials or exit and revoke them and re-run the installation.
Configure Dashboard Access¶
To access Weave GitOps Enterprise dashboard, you have the two following options available:
Access the dashboard¶
After installation is successful. The CLI will print out the URL where you can access the dashboard.
(Optional) Configure OIDC¶
OIDC configuration will enable you to login with OIDC provider beside, or instead of the admin credentials. Afte the installation is complete, you will be prompt if you want to configure OIDC access. If you don't want to set it up right away, you can do it later by running gitops-ee bootstrap auth --type=oidc command.
To configure OIDC access, you will be asked to provide the following values: DiscoveryUrl this will verify that OIDC is accessible and get the issuerUrl from the OIDC settings. clientID & clientSecret that you have configured on your OIDC static-clients.
Note
Please don't forget to add a new static-client on your OIDC provider settings with the redirectURI your-domain/oauth2/callback for example http://localhost:3000/oauth2/callback
CLI configurations¶
Install Weave GitOps Enterprise ENTERPRISE¶
Info
To purchase an entitlement to Weave GitOps Enterprise, please contact sales@weave.works. There is no need to install the open source version of Weave GitOps before installing Weave GitOps Enterprise.
Prerequisites¶
To get up and running with Weave GitOps Enterprise: - create a Kubernetes cluster - add your cluster to kubeconfig—which you'll get from Kubernetes—so that the kubeconfig correctly points to the management cluster - create a Git repository; in the instructions below, we refer to a fleet-infra repository - configure your Git client properly (if using GitHub, for example, then review their docs on setting your username and your email address) - obtain a valid entitlement secret from Weaveworks and apply it to your cluster - install a compatible version of Flux onto your cluster; see below for how-to guidance
Install the Weave GitOps Enterprise CLI Tool¶
To do this, you can use either brew or curl.
brew install weaveworks/tap/gitops-ee
+export VERSION=<VERSION>
+curl --silent --location "https://artifacts.wge.dev.weave.works/releases/bin/${VERSION}/gitops-$(uname)-$(uname -m).tar.gz" | tar xz -C /tmp
+sudo mv /tmp/gitops /usr/local/bin
+gitops version
+Install Flux Onto Your Cluster with the flux bootstrap Command¶
The flux bootstrap command enables you to deploy Flux on a cluster the GitOps way. Go here for more information about the command.
flux bootstrap github \
+--owner=<github username> \
+--repository=fleet-infra \
+--branch=main \
+--path=./clusters/management \
+--personal \
+--components-extra image-reflector-controller,image-automation-controller
+flux bootstrap gitlab \
+--owner=<gitlab username> \
+--repository=fleet-infra \
+--branch=main \
+--path=./clusters/management \
+--personal \
+--components-extra image-reflector-controller,image-automation-controller
+Your private Git repo should have a clusters/management folder that includes the manifests Flux needs to operate, and that also generates a key value pair for Flux to access the repo.
At this point your Flux management cluster should be running. Take a look at the repository you created earlier.
Apply Your Entitlements Secret to Your Cluster¶
As noted above, you receive your entitlements secret by contacting sales@weave.works. Use this command to apply it to the cluster:
kubectl apply -f entitlements.yaml
+Set up Authentication and RBAC¶
Securing Access to the Dashboard¶
There are two supported methods for logging in to the dashboard, that work with standard Kubernetes RBAC: - Login via an OIDC provider: recommended, as this will allow you to control permissions for existing users and groups that have already been configured to use OIDC. OIDC decouples the need to manage user lists from the application, allowing it to be managed via a central system designed for that purpose (i.e. the OIDC provider). OIDC also enables the creation of groups—either via your provider's own systems or by using a connector like Dex. - Login via a cluster user account: which is insecure, and which we only recommend for local and development environments or if you need to activate emergency access to a damaged cluster. However, it is an option if an OIDC provider is not available.
You may decide to give your engineering teams access to the WGE dashboard so they can view and manage their workloads. In this case, you will want to secure dashboard access and restrict who can interact with it. Weave GitOps Enterprise integrates with your OIDC provider and uses standard Kubernetes RBAC to give you fine-grained control of the dashboard users' permissions.
OIDC extends the OAuth2 authorization protocol by including an additional field (ID Token) that contains information (claims) about a user's identity. After a user successfully authenticates with the OIDC provider, Weave GitOps Enterprise uses this information to impersonate the user in any calls to the Kubernetes API. This allows cluster administrators to use RBAC rules to control access to the cluster and the dashboard.
To login via your OIDC provider, create a Kubernetes secret to store the OIDC configuration. This configuration consists of the following parameters:
| Parameter | Description | Default |
|---|---|---|
issuerURL | The URL of the issuer; typically, the discovery URL without a path | |
clientID | The client ID set up for Weave GitOps in the issuer | |
clientSecret | The client secret set up for Weave GitOps in the issuer | |
redirectURL | The redirect URL set up for Weave GitOps in the issuer—typically the dashboard URL, followed by /oauth2/callback | |
tokenDuration | The time duration that the ID Token will remain valid after successful authentication | "1h0m0s" |
tokenDuration | The time duration that the ID Token will remain valid after successful authentication | "1h0m0s" |
oidcUsernamePrefix | The prefix added to users when impersonating API calls to the Kubernetes API, equivalent to --oidc-username-prefix | |
oidcGroupsPrefix | The prefix added to groups when impersonating API calls to the Kubernetes API, equivalent to --oidc-groups-prefix |
Ensure that your OIDC provider has been set up with a client ID/secret and the dashboard's redirect URL.
Create a secret named oidc-auth in the flux-system namespace with these parameters set:
kubectl create secret generic oidc-auth \
+--namespace flux-system \
+--from-literal=issuerURL=<oidc-issuer-url> \
+--from-literal=clientID=<client-id> \
+--from-literal=clientSecret=<client-secret> \
+--from-literal=redirectURL=<redirect-url> \
+--from-literal=tokenDuration=<token-duration>
+Once the HTTP server starts, unauthenticated users will have to click 'Login With OIDC Provider' to log in or use the cluster account (if configured). Upon successful authentication, the users' identities will be impersonated in any calls made to the Kubernetes API, as part of any action they take in the dashboard. By default the Helm chart will configure RBAC correctly, but we recommend reading the service account and user permissions pages to understand which actions are needed for Weave GitOps to function correctly.
Customization¶
For some OIDC configurations, you may need to customise the requested scopes or claims.
The oidcUsernamePrefix and oidcGroupsPrefix work in the same way as the Kubernetes kube-apiserver command-line options, if you need them for Kubernetes, you will likely need them here.
Scopes¶
By default, the following scopes are requested: "openid","offline_access","email","groups".
The "openid" scope is mandatory for OpenID auth and will be added if not provided. The "email" and "groups" scopes are commonly used as unique identifiers in organisations.
"offline_access" allows us to refresh OIDC tokens to keep login sessions alive for as long as a refresh token is valid. You can, however, change the defaults.
kubectl create secret generic oidc-auth \
+--namespace flux-system \
+--from-literal=issuerURL=<oidc-issuer-url> \
+--from-literal=clientID=<client-id> \
+--from-literal=clientSecret=<client-secret> \
+--from-literal=redirectURL=<redirect-url> \
+--from-literal=tokenDuration=<token-duration> \
+--from-literal=customScopes=custom,scopes
+customScopes key is a comma-separated list of scopes to request. In this case, "custom", "scopes", and "openid" would be requested. Claims¶
By default, the following claims are parsed from the OpenID ID Token "email" and "groups". These are presented as the user and groups when WGE communicates with your Kubernetes API server.
This is equivalent to configuring your kube-apiserver with --oidc-username-claim=email --oidc-groups-claim=groups.
Again, you can configure these from the oidc-auth Secret.
kubectl create secret generic oidc-auth \
+--namespace flux-system \
+--from-literal=issuerURL=<oidc-issuer-url> \
+--from-literal=clientID=<client-id> \
+--from-literal=clientSecret=<client-secret> \
+--from-literal=redirectURL=<redirect-url> \
+--from-literal=tokenDuration=<token-duration> \
+--from-literal=claimUsername=sub \
+--from-literal=claimGroups=groups
+kube-apiserver configuration. Configuring OIDC with Dex and GitHub¶
This example uses Dex and its GitHub connector to show you how to log in to the Weave GitOps dashboard by authenticating with your GitHub account. It assumes you have already installed Weave GitOps on a Kubernetes cluster, per the instructions above, and have also enabled TLS.
Dex is an identity service that uses OpenID Connect to drive authentication for other apps. There are other solutions for identity and access management, such as Keycloak.
Create a namespace where you will install Dex:
---
+apiVersion: v1
+kind: Namespace
+metadata:
+name: dex
+Get a GitHub ClientID and Client secret by creating a new OAuth application.
kubectl create secret generic github-client \
+--namespace=dex \
+--from-literal=client-id=${GITHUB_CLIENT_ID} \
+--from-literal=client-secret=${GITHUB_CLIENT_SECRET}
+Deploy Dex¶
Use HelmRepository and HelmRelease objects to let Flux deploy everything.
Expand to see resource manifests
---
+apiVersion: source.toolkit.fluxcd.io/v1beta1
+kind: HelmRepository
+metadata:
+name: dex
+namespace: dex
+spec:
+interval: 1m
+url: https://charts.dexidp.io
+---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+name: dex
+namespace: dex
+spec:
+interval: 5m
+chart:
+ spec:
+ chart: dex
+ version: 0.15.3
+ sourceRef:
+ kind: HelmRepository
+ name: dex
+ namespace: dex
+ interval: 1m
+values:
+ envVars:
+ - name: GITHUB_CLIENT_ID
+ valueFrom:
+ secretKeyRef:
+ name: github-client
+ key: client-id
+ - name: GITHUB_CLIENT_SECRET
+ valueFrom:
+ secretKeyRef:
+ name: github-client
+ key: client-secret
+ config:
+ # Set it to a valid URL
+ issuer: https://dex.dev.example.tld
+
+ # See https://dexidp.io/docs/storage/ for more options
+ storage:
+ type: memory
+
+ staticClients:
+ - name: 'Weave GitOps'
+ id: weave-gitops
+ secret: AiAImuXKhoI5ApvKWF988txjZ+6rG3S7o6X5En
+ redirectURIs:
+ - 'https://localhost:9001/oauth2/callback'
+ - 'https://0.0.0.0:9001/oauth2/callback'
+ - 'http://0.0.0.0:9001/oauth2/callback'
+ - 'http://localhost:4567/oauth2/callback'
+ - 'https://localhost:4567/oauth2/callback'
+ - 'http://localhost:3000/oauth2/callback'
+
+ connectors:
+ - type: github
+ id: github
+ name: GitHub
+ config:
+ clientID: $GITHUB_CLIENT_ID
+ clientSecret: $GITHUB_CLIENT_SECRET
+ redirectURI: https://dex.dev.example.tld/callback
+ orgs:
+ - name: weaveworks
+ teams:
+ - team-a
+ - team-b
+ - QA
+ - name: ww-test-org
+ ingress:
+ enabled: true
+ className: nginx
+ annotations:
+ cert-manager.io/cluster-issuer: letsencrypt-prod
+ hosts:
+ - host: dex.dev.example.tld
+ paths:
+ - path: /
+ pathType: ImplementationSpecific
+ tls:
+ - hosts:
+ - dex.dev.example.tld
+ secretName: dex-dev-example-tld
+An important part of the configuration is the orgs field on the GitHub connector, which allows you to define groups within a GitHub organisation:
orgs:
+- name: weaveworks
+teams:
+- team-a
+- team-b
+- QA
+In this example, the GitHub organisation is weaveworks and all members of the team-a, team-b, and QA teams can authenticate. Group membership is added to the user.
Based on these groups, we can bind roles to groups:
Expand to see group role bindings
---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+name: wego-test-user-read-resources
+namespace: flux-system
+subjects:
+- kind: Group
+ name: weaveworks:QA
+ namespace: flux-system
+roleRef:
+kind: Role
+name: wego-admin-role
+apiGroup: rbac.authorization.k8s.io
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+name: wego-admin-role
+namespace: flux-system
+rules:
+- apiGroups: [""]
+ resources: ["secrets", "pods" ]
+ verbs: [ "get", "list" ]
+- apiGroups: ["apps"]
+ resources: [ "deployments", "replicasets"]
+ verbs: [ "get", "list" ]
+- apiGroups: ["kustomize.toolkit.fluxcd.io"]
+ resources: [ "kustomizations" ]
+ verbs: [ "get", "list", "patch" ]
+- apiGroups: ["helm.toolkit.fluxcd.io"]
+ resources: [ "helmreleases" ]
+ verbs: [ "get", "list", "patch" ]
+- apiGroups: ["source.toolkit.fluxcd.io"]
+ resources: ["buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories"]
+ verbs: ["get", "list", "patch"]
+- apiGroups: [""]
+ resources: ["events"]
+ verbs: ["get", "watch", "list"]
+In the same way, we can bind cluster roles to a group:
Expand to see group cluster role bindings
---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+name: weaveworks:team-a
+subjects:
+- kind: Group
+name: weaveworks:team-a
+apiGroup: rbac.authorization.k8s.io
+roleRef:
+kind: ClusterRole
+name: cluster-admin
+apiGroup: rbac.authorization.k8s.io
+Set up a Static User¶
For a static user, add staticPasswords to the config:
spec:
+values:
+ config:
+ staticPasswords:
+ - email: "admin@example.tld"
+ hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W"
+ username: "admin"
+ userID: "08a8684b-db88-4b73-90a9-3cd1661f5466"
+Generate a static user password via the gitops CLI:
PASSWORD="<your password>"
+echo -n $PASSWORD | gitops get bcrypt-hash
+$2a$10$OS5NJmPNEb13UgTOSKnMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q
+OIDC Login¶
Using the "Login with OIDC Provider" button:
We have to authorize the GitHub OAuth application:
After that, grant access to Dex:
Now we are logged in with our GitHub user and can see all of the resources we have access to:
Important
This is an insecure method of securing your dashboard which we only recommend for local and development environments, or if you need to activate emergency access to a damaged cluster.
Note also that this mechanism only exists for a single user. You will not be able to create multiple users. Weave GitOps does not provide its own authentication mechanism. For secure and fully-featured authentication we strongly recommend using an OIDC provider, as described in the other tab.
Configuring the Emergency User¶
Before you log in via the emergency user account, you need to generate a bcrypt hash for your chosen password and store it as a secret in Kubernetes. There are several different ways to generate a bcrypt hash. This guide uses gitops get bcrypt-hash from our CLI.
Generate the password by running:
PASSWORD="<your password>"
+echo -n $PASSWORD | gitops get bcrypt-hash
+$2a$10$OS5NJmPNEb13UgTOSKnMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q
+Now create a Kubernetes secret to store your chosen username and the password hash:
kubectl create secret generic cluster-user-auth \
+--namespace flux-system \
+--from-literal=username=wego-admin \
+--from-literal=password='$2a$10$OS5NJmPNEb13UTOSKngMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q'
+You should now be able to login via the cluster user account using your chosen username and password.
Updating the Emergency User¶
To change either the username or the password, recreate the cluster-user-auth with the new details.
Only one emergency user can be created this way. To add more users, enable an OIDC provider.
User Permissions¶
By default, both a ClusterRole and Role are generated for the emergency user. Both have the same permissions, with the former being optional and the latter being bound to the flux-system namespace (where Flux stores its resources by default). The default set of rules are configured like this:
rules:
+# Flux Resources
+- apiGroups: ["source.toolkit.fluxcd.io"]
+ resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ]
+ verbs: [ "get", "list", "watch", "patch" ]
+
+- apiGroups: ["kustomize.toolkit.fluxcd.io"]
+ resources: [ "kustomizations" ]
+ verbs: [ "get", "list", "watch", "patch" ]
+
+- apiGroups: ["helm.toolkit.fluxcd.io"]
+ resources: [ "helmreleases" ]
+ verbs: [ "get", "list", "watch", "patch" ]
+
+- apiGroups: [ "notification.toolkit.fluxcd.io" ]
+ resources: [ "providers", "alerts" ]
+ verbs: [ "get", "list", "watch", "patch" ]
+
+- apiGroups: ["infra.contrib.fluxcd.io"]
+ resources: ["terraforms"]
+ verbs: [ "get", "list", "watch", "patch" ]
+
+# Read access for all other Kubernetes objects
+- apiGroups: ["*"]
+ resources: ["*"]
+ verbs: [ "get", "list", "watch" ]
+These permissions give the emergency user Administrator-level powers. We do not advise leaving it active on production systems.
If required, the permissions can be expanded with the rbac.additionalRules field in the Helm Chart. Follow the instructions in the next section in order to configure RBAC correctly.
Note
To remove the emergency user as a login method, set the following values in the Helm Chart:
#
+adminUser:
+create: false
+#
+additionalArgs:
+- --auth-methods=oidc
+#
+If you are disabling an already existing emergency user, you will need to manually delete the Kubernetes Secret and any User Roles that were created on the cluster.
GitOps Dashboard Service Account Permissions¶
This section covers the service account permissions for the Weave GitOps application, which the WGE UI requires to work. The default permissions will generate a cluster role that includes the permissions:
rules:
+- apiGroups: [""]
+ resources: ["users", "groups"]
+ verbs: [ "impersonate" ]
+- apiGroups: [""]
+ resources: [ "secrets" ]
+ verbs: [ "get", "list" ]
+- apiGroups: [ "" ]
+ resources: [ "namespaces" ]
+ verbs: [ "get", "list" ]
+These allow the pod to do three things: - Impersonate the user and operate in the cluster as them - Read the available namespaces; this is required to understand users' permissions - Read the cluster-user-auth and oidc-auth secrets, the default secrets to store the emergency cluster user account and OIDC configuration (see securing access to the dashboard)
Impersonation¶
The primary way Weave GitOps queries the Kube API is via impersonation. The permissions granted to users and groups that Weave GitOps can impersonate will determine the scope of actions that WGE can take within your cluster.
The application, not the cluster, authenticates the user, either via the emergency cluster user credentials or OIDC. Then it makes Kube API calls on the user's behalf. This is equivalent to making a kubectl call like:
$ kubectl get deployments --as aisha@example.com
+Assuming the user aisha@example.com has permissions to get deployments within the cluster, this will return those deployments. The same occurs within the application, so properly configuring application permissions is very important. Without proper restrictions the application can impersonate very powerful users or groups. For example, the system:masters is a group generally bound to the cluster-admin role, which can do anything.
Get Namespaces¶
The application itself uses get namespace permissions to pre-cache the list of available namespaces. As the user accesses resources their permissions within various namespaces is also cached to speed up future operations.
Reading the cluster-user-auth and oidc-auth Secrets¶
The cluster-user-auth and oidc-auth secrets provide information for authenticating to the application. The former holds the username and bcrypt-hashed password for the emergency user, and the latter holds OIDC configuration.
The application needs to be able to access these secrets in order to authenticate users.
User Permissions¶
This section discusses the Kubernetes permissions needed by Weave GitOps application users and groups. At a minimum, a User should be bound to a Role in the flux-system namespace—which is where Flux stores its resources by default—with the following permissions:
rules:
+ # Flux Resources
+ - apiGroups: ["source.toolkit.fluxcd.io"]
+ resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ]
+ verbs: [ "get", "list", "watch", "patch" ]
+
+ - apiGroups: ["kustomize.toolkit.fluxcd.io"]
+ resources: [ "kustomizations" ]
+ verbs: [ "get", "list", "watch", "patch" ]
+
+ - apiGroups: ["helm.toolkit.fluxcd.io"]
+ resources: [ "helmreleases" ]
+ verbs: [ "get", "list", "watch", "patch" ]
+
+ - apiGroups: [ "notification.toolkit.fluxcd.io" ]
+ resources: [ "providers", "alerts" ]
+ verbs: [ "get", "list", "watch", "patch" ]
+
+ - apiGroups: ["infra.contrib.fluxcd.io"]
+ resources: ["terraforms"]
+ verbs: [ "get", "list", "watch", "patch" ]
+
+ # Read access for all other Kubernetes objects
+ - apiGroups: ["*"]
+ resources: ["*"]
+ verbs: [ "get", "list", "watch" ]
+For a wider scope, the User can be bound to a ClusterRole with the same set.
On top of this you can add other permissions to view WGE resources like GitOpsSets and Templates.
Flux Resources¶
The following table lists resources that Flux works with directly.
| API Group | Resources | Permissions |
|---|---|---|
| kustomize.toolkit.fluxcd.io | kustomizations | get, list, patch |
| helm.toolkit.fluxcd.io | Helm Releases | get, list, patch |
| source.toolkit.fluxcd.io | buckets, Helm charts, Git repositories, Helm repositories, OCI repositories | get, list, patch |
| notification.toolkit.fluxcd.io | providers, alerts | get, list |
| infra.contrib.fluxcd.io | Terraform | get, list, patch |
Weave GitOps needs to be able to query the CRDs that Flux uses before it can accurately display Flux state. The get and list permissions facilitate this.
The patch permissions are used for two features: to suspend and resume reconciliation of a resource by modifying the 'spec' of a resource, and to force reconciliation of a resource by modifying resource annotations. These features work in the same way that flux suspend, flux resume, and flux reconcile does on the CLI.
Resources Managed via Flux¶
| API Group | Resources | Permissions |
|---|---|---|
| "" | configmaps, secrets, pods, services, persistent volumes, persistent volume claims | get, list, watch |
| apps | deployments, replica sets, stateful sets | get, list, watch |
| batch | jobs, cron jobs | get, list, watch |
| autoscaling | horizontal pod autoscalers | get, list, watch |
| rbac.authorization.k8s.io | roles, cluster roles, rolebindings, cluster role bindings | get, list, watch |
| networking.k8s.io | ingresses | get, list, watch |
Weave GitOps reads basic resources so that it can monitor the effect that Flux has on what's running.
Reading secrets enables Weave GitOps to monitor the state of Helm releases as that's where it stores the state by default. For clarity this these are the Helm release objects not the Flux HelmRelease resource (which are dealt with by the earlier section).
Feedback from Flux¶
Flux communicates the status of itself primarily via events. These events will show when reconciliations start and stop, whether they're successful, and information as to why they're not.
Login UI¶
The label of the OIDC button on the login screen is configurable via a feature flag environment variable. This can give your users a more familiar experience when logging in.
Adjust the configuration in the Helm values.yaml file or the spec.values section of the Weave GitOps HelmRelease resource:
extraEnvVars:
+ - name: WEAVE_GITOPS_FEATURE_OIDC_BUTTON_LABEL
+ value: "Login with ACME"
+Recommended RBAC Configuration¶
This section is purposefully vague as we intend to give a broad idea of how to implement such a system. The specifics will dependent on your circumstances and goals.
Our general recommendation is to use OIDC and a small number of groups that Weave GitOps can impersonate.
Configuring Weave GitOps to impersonate Kubernetes groups rather than users has the following benefits: - A user's permissions for impersonation by Weave GitOps can be separate from any other permissions that they may or may not have within the cluster. - Users do not have to be individually managed within the cluster and can have their permissions managed together.
Example Setup¶
Assume that your company has the following people in OIDC: - Aisha, a cluster admin, who should have full admin access to Weave GitOps - Brian, lead of Team-A, who should have admin permissions to their team's namespace in Weave GitOps and read-only otherwise - June and Jo, developers in Team-A who should have read-only access to Weave GitOps
You can then create three groups:
Using OIDC for cluster and Weave GitOps Authentication
If the same OIDC provider is used to authenticate a user with the cluster itself (e.g. for use with kubectl) and to Weave GitOps then, depending on OIDC configuration, they may end up with the super-set of their permissions from Weave GitOps and any other permissions granted to them.
This can lead to unintended consequences, like viewing secrets. To avoid this, OIDC providers will often let you configure which groups are returned to which clients. The Weave GitOps groups should not be returned to the cluster client (and vice versa).
Code¶
The yaml to configure these permissions would look roughly like:
Expand to see example RBAC
# Admin cluster role
+ apiVersion: rbac.authorization.k8s.io/v1
+ kind: ClusterRole
+ metadata:
+ name: wego-admin-cluster-role
+ rules:
+ - apiGroups: [""]
+ resources: ["secrets", "pods" ]
+ verbs: [ "get", "list" ]
+ - apiGroups: ["apps"]
+ resources: [ "deployments", "replicasets"]
+ verbs: [ "get", "list" ]
+ - apiGroups: ["kustomize.toolkit.fluxcd.io"]
+ resources: [ "kustomizations" ]
+ verbs: [ "get", "list", "patch" ]
+ - apiGroups: ["helm.toolkit.fluxcd.io"]
+ resources: [ "helmreleases" ]
+ verbs: [ "get", "list", "patch" ]
+ - apiGroups: ["source.toolkit.fluxcd.io"]
+ resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ]
+ verbs: [ "get", "list", "patch" ]
+ - apiGroups: [""]
+ resources: ["events"]
+ verbs: ["get", "watch", "list"]
+ ---
+ # Read-only cluster role
+ apiVersion: rbac.authorization.k8s.io/v1
+ kind: ClusterRole
+ metadata:
+ name: wego-readonly-role
+ rules:
+ # All the 'patch' permissions have been removed
+ - apiGroups: [""]
+ resources: ["secrets", "pods" ]
+ verbs: [ "get", "list" ]
+ - apiGroups: ["apps"]
+ resources: [ "deployments", "replicasets"]
+ verbs: [ "get", "list" ]
+ - apiGroups: ["kustomize.toolkit.fluxcd.io"]
+ resources: [ "kustomizations" ]
+ verbs: [ "get", "list" ]
+ - apiGroups: ["helm.toolkit.fluxcd.io"]
+ resources: [ "helmreleases" ]
+ verbs: [ "get", "list" ]
+ - apiGroups: ["source.toolkit.fluxcd.io"]
+ resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ]
+ verbs: [ "get", "list" ]
+ - apiGroups: [""]
+ resources: ["events"]
+ verbs: ["get", "watch", "list"]
+ ---
+ # Bind the cluster admin role to the wego-admin group
+ apiVersion: rbac.authorization.k8s.io/v1
+ kind: ClusterRoleBinding
+ metadata:
+ name: wego-cluster-admin
+ subjects:
+ - kind: Group
+ name: wego-admin # only Aisha is a member
+ apiGroup: rbac.authorization.k8s.io
+ roleRef:
+ kind: ClusterRole
+ name: wego-admin-cluster-role
+ apiGroup: rbac.authorization.k8s.io
+ ---
+ # Bind the admin role in the team-a namespace for the wego-team-a-admin group
+ apiVersion: rbac.authorization.k8s.io/v1
+ kind: RoleBinding
+ metadata:
+ name: wego-team-a-admin-role
+ namespace: team-a
+ subjects:
+ - kind: Group
+ name: wego-team-a-admin # Aisha & Brian are members
+ apiGroup: rbac.authorization.k8s.io
+ roleRef:
+ # Use the cluster role to set rules, just bind them in the team-a namespace
+ kind: ClusterRole
+ name: wego-admin-role
+ apiGroup: rbac.authorization.k8s.io
+ ---
+ # Bind the read-only role to the read-only group
+ apiVersion: rbac.authorization.k8s.io/v1
+ kind: ClusterRoleBinding
+ metadata:
+ name: wego-readonly-role
+ subjects:
+ - kind: Group
+ name: wego-readonly # Everyone is a member
+ apiGroup: rbac.authorization.k8s.io
+ roleRef:
+ kind: ClusterRole
+ name: wego-readonly-role
+ apiGroup: rbac.authorization.k8s.io
+ ---
+Configure Access for Writing to Git from the Weave GitOps Enterprise UI¶
Here we provide guidance for GitHub, GitLab, BitBucket Server, and Azure DevOps.
GitHub requires no additional configuration for OAuth git access
Create a GitLab OAuth application that will request api permissions to create pull requests on your behalf.
Follow the GitLab docs.
The application should have at least these scopes:
Add callback URLs to the application for each address the UI will be exposed on, e.g.:
Save your application, taking note of the Client ID and Client Secret. Save them into the git-provider-credentials secret, along with:
Replace values in this snippet and run:
kubectl create secret generic git-provider-credentials --namespace=flux-system \
+--from-literal="GITLAB_CLIENT_ID=13457" \
+--from-literal="GITLAB_CLIENT_SECRET=24680" \
+--from-literal="GITLAB_HOSTNAME=git.example.com" \
+--from-literal="GIT_HOST_TYPES=git.example.com=gitlab"
+Create a new incoming application link from the BitBucket administration dashboard. You will be asked to enter a unique name and the redirect URL for the external application. The redirect URL should be set to <WGE dashboard URL>/oauth/bitbucketserver. You will also need to select permissions for the application. The minimum set of permissions needed for WGE to create pull requests on behalf of users is Repositories - Write. An example of configuring these settings is shown below.
Save your application and take note of the Client ID and Client Secret. Save them into the git-provider-credentials secret, along with:
Replace values in this snippet and run:
kubectl create secret generic git-provider-credentials --namespace=flux-system \
+--from-literal="BITBUCKET_SERVER_CLIENT_ID=13457" \
+--from-literal="BITBUCKET_SERVER_CLIENT_SECRET=24680" \
+--from-literal="BITBUCKET_SERVER_HOSTNAME=git.example.com" \
+--from-literal="GIT_HOST_TYPES=git.example.com=bitbucket-server"
+If the secret is already present, use the following command to update it using your default editor:
kubectl edit secret generic git-provider-credentials --namespace=flux-system
+Info
If BitBucket Server is running on the default port (7990), make sure you include the port number in the values of the secret. For example: GIT_HOST_TYPES=git.example.com:7990=bitbucket-server
Navigate to VisualStudio and register a new application, as explained in the docs. Set the authorization callback URL and select which scopes to grant. Set the callback URL to <WGE dashboard URL>/oauth/azuredevops.
Select the Code (read and write) scope from the list. This is necessary so that WGE can create pull requests on behalf of users. An example of configuring these settings is shown below.
After creating your application, you will be presented with the application settings. Take note of the App ID and Client Secret values—you will use them to configure WGE.
In your cluster, create a secret named git-provider-credentials that contains the App ID and Client Secret values from the newly created application.
Replace values in this snippet and run:
kubectl create secret generic git-provider-credentials --namespace=flux-system \
+--from-literal="AZURE_DEVOPS_CLIENT_ID=<App ID value>" \
+--from-literal="AZURE_DEVOPS_CLIENT_SECRET=<Client Secret value>"
+WGE is now configured to ask users for authorization the next time a pull request must be created as part of using a template. Note that each user can view and manage which applications they have authorized by navigating to https://app.vsaex.visualstudio.com/me.
TLS Configuration¶
By default, the WGE UI pod will listen on port 8000 with TLS enabled. WGE will generate and use a self-signed certificate for this purpose.
It can then be accessed via port-forwarding:
kubectl port-forward --namespace flux-system svc/clusters-service 8000:8000
If you're using an ingress controller to terminate TLS you can disable it in the Helm release:
values:
+ tls:
+ enabled: false
+Other ingress conguration changes can be made via the ingress configuration
values:
+ ingress:
+ enabled: true
+ ... other parameters specific to the ingress type ...
+Configure Helm Chart and Commit¶
We deploy WGE via a Helm chart. We'll save and adapt the below template before committing it in Git to a Flux-reconciled path.
Clone the newly created repo locally. We're gonna add some things!
git clone git@<provider>:<username>/fleet-infra
+cd fleet-infra
+Download the helm-release to clusters/management/weave-gitops-enterprise.yaml.
import ExampleWGE from "../assets/example-enterprise-helm.yaml"; import ExampleWGEContent from "!!raw-loader!../assets/example-enterprise-helm.yaml";
Expand to see file contents
Once you have copied the above file, open and adjust the following configuration options:
values.config.capi.repositoryURL¶
Ensure this has been set to your repository URL.
values.config.capi.repositoryPath¶
By default, WGE will create new clusters in the clusters/management/clusters path. You can configure it with values.config.capi.repositoryPath. You might what to change it to clusters/my-cluster/cluster if you configured Flux to reconcile ./clusters/my-cluster instead.
values.config.capi.repositoryClustersPath¶
The other important path to configure is where you'll store applications and workloads run on the new cluster. By default this is ./clusters. When a new cluster is specified, any selected profiles will be written to ./clusters/{.namespace}/{.clusterName}/profiles.yaml. When the new cluster is bootstrapped, Flux will sync the ./clusters/{.namespace}/{.clusterName} path.
Configure Your Password¶
To login to the WGE UI, generate a bcrypt hash for your chosen password and store it as a secret in the Kubernetes cluster. There are several different ways to generate a bcrypt hash. Here, we'll use gitops get bcrypt-hash from our CLI.
PASSWORD="<Make up and insert a brand-new password here>"
+echo -n $PASSWORD | gitops get bcrypt-hash | kubectl create secret generic cluster-user-auth -n flux-system --from-literal=username=wego-admin --from-file=password=/dev/stdin
+A validation to know it’s working:
kubectl get secret -n flux-system cluster-user-auth
+(Optional) Install Policy Agent¶
Policy agent comes packaged with the WGE chart. To install it, set the following values:
Commit and push all the files
git add clusters/management/weave-gitops-enterprise.yaml
+git commit -m "Deploy Weave GitOps Enterprise"
+git push
+Flux will reconcile the helm-release and WGE will be deployed into the cluster. You can check the flux-system namespace to verify all pods are running.
Next Steps¶
Here are a couple of options for you to take your next steps with WGE. Explore one option or all of them, in no particular order.
Joining a Cluster with Azure Flux ENTERPRISE¶
Prerequisites¶
See also our guide to installing Weave GitOps Enterprise on Azure: - An Azure cluster deployed with either the Azure Portal or Azure CLI tools. - Azure Flux add-on deployed by adding a GitOps configuration, either via the Azure Portal or the CLI tool.
Note that this documentation applies to both Azure AKS and Azure ARC clusters.
Initial Status¶
The Azure cluster already has the Azure Flux add-on installed. This differs from CNCF Flux in that there are two additional controllers: - fluxconfig-agent - fluxconfig-controller
These controllers have CRDs that define the version of Flux and any Flux Kustomizations that are managed via the Azure CLI.
The CRDs are all apiVersion: clusterconfig.azure.com/v1beta1.
The Kinds are: - FluxConfig - FluxConfigSyncStatus
The FluxConfig Kind configures Flux itself and creates any Kustomizations that refer to a single-source GitRepository. This guide assumes that this process is already completed and that a top-level Kustomization has been configured for the fleet repo cluster directory already set up at clusters/default/CLUSTER_NAME/manifests.
The CRDs that this FluxConfig generates are Flux CRDs, as follows: - GitRepositories - Kustomizations
These generated resources are viewable through Weave GitOps Enterprise.
Weave GitOps itself is deployed by Flux using a HelmRelease that pulls the Helm Chart. It doesn’t need to install Flux, as it is assumed that Flux is already deployed. Therefore it can use the Azure Flux add-on, which poses no conflicts with WGE itself.
Incompatibilities exist between the Azure Flux add-on and CNCF Flux. They should not be run at the same time, on the same cluster, due to conflicts in the CRD management. If the Flux bootstrapping process IS run on a cluster with Azure Flux add-on, it will override the Azure Flux add-on with the Flux version used in the bootstrap. Also, it would add Flux manifests to the source Git repository. This would be undesirable.
Azure Flux add-on-enabled clusters keep the Azure Flux add-on in place.
Joining a Cluster to WGE¶
Setting up a Service Account¶
To join a cluster, you'll set up a service account with permissions and create a kubeconfig for the service account. This service account does not need cluster admin permissions unless you are bootstrapping Flux into the cluster. The bootstrapping process will either be A) carried out before joining the cluster to WGE; or B) configured specifically for Flux to be bootstrapped into the cluster from WGE.
If you already have Flux running, you can create the service account in your fleet repo:
Expand to see role manifests
apiVersion: v1
+kind: ServiceAccount
+metadata:
+name: wgesa
+namespace: default
+---
+apiVersion: v1
+kind: Secret
+type: kubernetes.io/service-account-token
+metadata:
+name: wgesa-secret
+namespace: default
+annotations:
+ kubernetes.io/service-account.name: "wgesa"
+Expand to see role manifests
apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+ name: impersonate-user-groups
+subjects:
+ - kind: ServiceAccount
+ name: wgesa
+ namespace: default
+roleRef:
+ kind: ClusterRole
+ name: user-groups-impersonator
+ apiGroup: rbac.authorization.k8s.io
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+ name: user-groups-impersonator
+rules:
+ - apiGroups: [""]
+ resources: ["users", "groups"]
+ verbs: ["impersonate"]
+ - apiGroups: [""]
+ resources: ["namespaces"]
+ verbs: ["get", "list"]
+Kubernetes 1.24+ will not create secrets for Service Accounts for you, so you have to add it yourself.
You can also take care of this step in WGE's Secrets UI, setting up a a secret in SOPS or ESO.
Flux CRDs are compatible with the Azure Flux Configuration CRDs. This means that there are no compatibility issues between WGE and Azure Flux.
Using WGE to Deploy Clusters¶
With Cluster API¶
MSFT maintains CAPZ, the Azure CAPI provider. Currently there is no support for Azure Flux. A CAPI-based cluster will continue to run the Flux bootstrap process on cluster creation when managed by WGE, because there is no Azure Flux option.
With Terraform Provider¶
WGE uses TF-controller to deploy Terraform resources. For WGE to use the cluster as a target requires A) a resource created in the management cluster and B) a kubeconfig that maps to a service account in the target cluster. The Terraform cluster build typically creates this service account and then outputs to a secret store or local secret so that WGE can use it as a cluster. The Flux bootstrap process can be initiated directly with the Flux Terraform module, which deploys CNCF Flux to the target cluster.
Alternatively, you can apply an Azure Policy to provide the Azure Flux add-on. This is an example of how you can use the policy controls. This means you could come across clusters that are deployed with Terraform with the Azure Flux add-on already installed and would not run the Flux bootstrap process.
Either way, it is typical that Terraform-deployed clusters do not run the Flux bootstrap process at all, because it is usually already installed.
With Crossplane¶
The Azure Flux add-on is supported under Crossplane-deployed Azure clusters. Any clusters deployed with Crossplane that have the Azure Flux add-on enabled would also be added to WGE without running the bootstrap process.
Releases ENTERPRISE¶
Info
This page details the changes for Weave GitOps Enterprise and its associated components. For Weave GitOps OSS, please see the release notes on GitHub.
v0.31.0¶
2023-08-31
Highlights¶
Dependency versions¶
v0.30.0¶
2023-08-17
Highlights¶
UI¶
Policy¶
GitOpsSets¶
Dependency versions¶
v0.29.1¶
2023-08-04
Warning
This release builds upon Weave GitOps v0.29.0 that has breaking changes from Flux v2.0.0. Please make sure that you read these release notes.
Dependency versions¶
🚀 Enhancements¶
v0.29.0¶
2023-08-03
Danger
⚠️ Breaking changes¶
We introduced a breaking change in this release by upgrading to Flux v2 APIs, notably GitRepository v1, Kustomization v1, and Receiver v1. This means that this version of Weave GitOps Enterprise is not compatible with previous versions of Flux v2, such as v0.41.x and earlier.
✍️ Action required¶
Follow Flux or Weave GitOps to upgrade to Flux v2 GA before upgrading Weave GitOps Enterprise.
Highlights¶
Flux¶
Explorer¶
Dependency versions¶
🚀 Enhancements¶
🔥 UI¶
v0.28.0¶
2023-07-20
Highlights¶
UI¶
Explorer¶
Breaking Changes¶
Dependency versions¶
v0.27.0¶
2023-07-07
Highlights¶
Explorer¶
GitOpsSets¶
UI¶
Dependency versions¶
v0.26.0¶
2023-06-22
Highlights¶
Dependency versions¶
v0.25.0¶
2023-06-08
Bug fixes
Dependency versions¶
v0.24.0¶
2023-05-25
Highlights¶
GitOpsSets¶
Profiles and Charts¶
Explorer¶
Breaking Changes¶
(none)
Known issues¶
Explorer¶
Dependency versions¶
v0.23.0¶
2023-05-12
Highlights¶
Application Details¶
Explorer¶
Templates¶
Cluster details¶
Explorer¶
Dependency versions¶
v0.22.0¶
2023-04-27
Highlights¶
Explorer¶
GitopsSets¶
Cluster Bootstrapping¶
Upgrade Notes (from the previous release)¶
Known issues¶
Dependency versions¶
v0.21.2¶
2023-04-13
Highlights¶
Dependency versions¶
v0.20.0¶
2023-03-30
Dependency versions¶
v0.19.0¶
2023-03-16
Highlights¶
UI¶
Dependency versions¶
v0.18.0¶
2023-03-02
Highlights¶
UI¶
GitopsSets¶
Dependency versions¶
v0.17.0¶
2023-02-16
Highlights¶
This release contains dependency upgrades and bug fixes. For a larger list of updates, check out the Weave GitOps v0.17.0 release.
v0.16.0¶
2023-02-02
Highlights¶
Create External Secrets via WGE UI¶
Plan Button in Terraform¶
Dependency versions¶
Breaking changes¶
No breaking changes
v0.15.1¶
2023-01-19
Highlights¶
Multi Repository support. Weave GitOps Enterprise adapts and scales to your repository structure¶
GitOps Templates¶
GitOps Templates CLI enhancements¶
GitOpsSets in preview¶
Minor fixes¶
OIDC¶
Dependency versions¶
Breaking changes¶
No breaking changes
v0.14.1¶
2023-01-05
Highlights¶
Secrets management¶
Pipelines¶
Minor fixes¶
Workspaces¶
[UI] "Tenant" is renamed to "Workspace" on details page.
[UI] Use time.RFC3339 format for all timestamps of the workspaces tabs.
Other¶
[UI] Error notification boundary does not allow user to navigate away from the page.
[Gitops run] GitOps Run doesn't ask to install dashboard twice
Dependency versions¶
Breaking changes¶
No breaking changes
v0.13.0¶
2022-12-22
Highlights¶
GitOps Templates Path feature¶
spec:
+ resourcetemplates:
+ - path: ./clusters/${CLUSTER_NAME}/definition/cluster.yaml
+ content:
+ - apiVersion: cluster.x-k8s.io/v1alpha4
+ kind: Cluster
+ metadata:
+ name: ${CLUSTER_NAME}
+ ...
+ - apiVersion: infrastructure.cluster.x-k8s.io/v1alpha4
+ kind: AWSCluster
+ metadata:
+ name: ${CLUSTER_NAME}
+ ...
+ - path: ./clusters/${CLUSTER_NAME}/workloads/helmreleases.yaml
+ content:
+ - apiVersion: helm.toolkit.fluxcd.io/v2beta1
+ kind: HelmRelease
+ metadata:
+ name: ${CLUSTER_NAME}-nginx
+ ...
+ - apiVersion: helm.toolkit.fluxcd.io/v2beta1
+ kind: HelmRelease
+ metadata:
+ name: ${CLUSTER_NAME}-cert-manager
+ ...
+Workspace UI¶
Enhanced Terraform Table in UI¶
Keyboard shortcuts for "port forwards" on GitOps Run¶
Minor fixes¶
[UI] Notifications Fixed provider page showing a 404.
Dependency versions¶
Breaking changes¶
No breaking changes
v0.12.0¶
2022-12-09
Highlights¶
We highly recommend users of v0.11.0 upgrade to this version as it includes fixes for a number of UI issues.
GitOps Templates¶
spec:
+ charts:
+ items:
+ - chart: cert-manager
+ version: v1.5.3
+ editable: false
+ required: true
+ values:
+ installCRDs: ${CERT_MANAGER_INSTALL_CRDS}
+ targetNamespace: cert-manager
+ layer: layer-1
+ template:
+ content:
+ metadata:
+ labels:
+ app.kubernetes.io/name: cert-manager
+ spec:
+ retries: ${CERT_MANAGER_RETRY_COUNT}
+Authentication with OIDC support¶
Supporting custom OIDC groups claims for azure/okta integration Support for OIDC custom username and group claims:
config
+ oidc:
+ claimUsername: ""
+ claimGroups: ""
+Policy commit-time agent¶
Admin User- simpler RBAC¶
Pipelines - adding Pipelines through Templates¶
Support for multiple Flux instances on a single cluster¶
Minor fixes¶
Terraform CRD Error Users of the Terraform Controller will be pleased to know we’ve addressed the issue where an error would be displayed if it had not been installed on all connected clusters.
Management cluster renaming If the name of the cluster where Weave GitOps Enterprise is installed, was changed from the default of management through the config.cluster.name parameter, certain workflows could fail such as fetching profiles, this has now been resolved.
Dependency versions¶
weave-gitops v0.12.0 cluster-controller v1.4.1 cluster-bootstrap-controller v0.3.0 (optional) pipeline-controller v0.0.11 (optional) policy-agent 2.1.1
Known issues¶
v0.11.0¶
2022-11-25
Highlights¶
GitOpsTemplates¶
Pipelines¶
Telemetry¶
This release incorporates anonymous aggregate user behavior analytics to help us continuously improve the product. As an Enterprise customer, this is enabled by default. You can learn more about this here.
Dependency versions¶
Breaking changes¶
GitOpsTemplates and CAPITemplates¶
We are making these changes to provide a unified and intuitive self-service experience within Weave GitOps Enterprise, removing misleading and potentially confusing terminology born from when only Clusters were backed by Templates.
New API Group for the GitOpsTemplate CRD - old: clustertemplates.weave.works - new: templates.weave.works
After upgrading Weave GitOps Enterprise which includes the updated CRD: 1. Update all your GitOpsTemplates in Git changing all occurrences of apiVersion: clustertemplates.weave.works/v1alpha1 to apiVersion: templates.weave.works/v1alpha1. 2. Commit, push and reconcile. They should now be viewable in the Templates view again. 3. Clean up the old CRD. As it stands: - kubectl get gitopstemplate -A will be empty as it is pointing to the old clustertemplates.weave.works CRD. - kubectl get gitopstemplate.templates.weave.works -A will work To fix the former of the commands, remove the old CRD (helm does not do this automatically for safety reasons): - kubectl delete crd gitopstemplates.clustertemplates.weave.works - You may have to wait up to 5 minutes for your local kubectl CRD cache to invalidate, then kubectl get gitopstemplate -A should be working as usual
Template Profiles / Applications / Credentials sections are hidden by default
For both CAPITemplates and GitopsTemplates the default visibility for all sections in a template has been set to "false". To re-enable profiles or applications on a template you can tweak the annotations
annotations:
+ templates.weave.works/profiles-enabled: "true" # enable profiles
+ templates.weave.works/kustomizations-enabled: "true" # enable applications
+ templates.weave.works/credentials-enabled: "true" # enable CAPI credentials
+The default values for a profile are not fetched and included in a pull-request
Prior to this release WGE would fetch the default values.yaml for every profile installed and include them in the HelmReleases in the Pull Request when rendering out the profiles of a template.
This was an expensive operation and occasionally led to timeouts.
The new behaviour is to omit the values and fall back to the defaults included in the helm-chart. This sacrifices some UX (being able to see all the defaults in the PR and tweak them) to improve performance. There should not be any final behaviour changes to the installed charts.
You can still view and tweak the values.yaml when selecting profiles to include on the "Create resource (cluster)" page. If changes are made here the updated values.yaml will be included.
v0.10.2¶
2022-11-15
Highlights¶
Dependency versions¶
v0.10.1¶
2022-11-10
Highlights¶
Dependency versions¶
v0.9.6¶
2022-10-17
Highlights¶
Dependency versions¶
v0.9.5¶
2022-09-22
Highlights¶
Dependency versions¶
Known issues¶
⚠️ Breaking changes from v0.9.4¶
If using the policy-agent included in the weave-gitops-enterprise helm chart, the configuration should now be placed under the config key.
old
policy-agent:
+ enabled: true
+ accountId: "my-account"
+ clusterId: "my-cluster"
+new
policy-agent:
+ enabled: true
+ config:
+ accountId: "my-account"
+ clusterId: "my-cluster"
+Configuration ENTERPRISE¶
Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
This page helps you to understand the options available to configure Explorer
Prerequisites¶
Before using Explorer, please ensure that: - You have Weave Gitops Enterprise v0.23.0
Setup¶
The following configuration options are available for you to setup Explorer.
You should specify them in your HelmRelease values:
---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+ name: weave-gitops-enterprise
+ namespace: flux-system
+spec:
+ # ... other spec components
+ values:
+ enableExplorer: true # feature flag to enable explorer
+ useQueryServiceBackend: true # uses explorer query backend in collection UIs
+ explorer:
+ collector:
+ serviceAccount: # service account that collector will impersonate in leaf clusters
+ name: collector
+ namespace: flux-system
+Configuration¶
Clusters¶
Explorer watches the GitopsClusters that you have connected to Weave Gitops Enterprise, as well as your Management cluster.
Kinds¶
Explorer watches for the following kind resources out of the box:
Weave Gitops - GitopsSets - Templates - Policy Audit Violations
Data Layer¶
Explorer take a simple approach to manage resource views. It leverages a Data Store for caching the views and query them. The storage lifecycle is bounded to Weave Gitops Enterprise app and does not provide persistence guarantees. Instead, it requests data as required to the leaf clusters. In its simplest form, the data store used is SQLite.
Authentication and Authorization¶
There are two main paths to consider within Explorer in the context of authentication and authorization (authN/authZ):
We look into them separately.
Authentication and Authorization for querying¶
Explorer leverages existing authentication and authorization built-in the application. It identifies for a user logged in the application: its identity and the access permissions via Kuberentes RBAC. Query results are filtered honouring the access determined via RBAC.
Authentication and Authorization for collecting¶
GitopsClusters define the connection and security context that Explorer leverages to collect data from leaf clusters. Given that you have followed the indications in setup RBAC, the GitopsCluster service account is able to impersonate any user or group.
Tip
Collector RBAC resources are part of your leaf clusters common RBAC configuration. It is commonly located in your clusters/bases folder, as described in Getting started.
To configure collection, you would need to extend this configuration with the following:
Expand to see example
apiVersion: v1
+kind: ServiceAccount
+metadata:
+name: collector # should match .spec.values.explorer.collector.serviceAccount.name
+namespace: flux-system # should match .spec.values.explorer.collector.serviceAccount.namespace
+Expand to see example
apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+name: collector # could be .spec.values.explorer.collector.serviceAccount.name
+rules:
+- apiGroups: [ "rbac.authorization.k8s.io" ]
+ resources: [ "roles", "clusterroles", "rolebindings", "clusterrolebindings" ]
+ verbs: [ "list", "watch" ]
+- apiGroups: [ "kustomize.toolkit.fluxcd.io" ]
+ resources: [ "kustomizations" ]
+ verbs: [ "list", "watch" ]
+- apiGroups: [ "helm.toolkit.fluxcd.io" ]
+ resources: [ "helmreleases" ]
+ verbs: [ "list", "watch" ]
+- apiGroups: [ "source.toolkit.fluxcd.io" ]
+ resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ]
+ verbs: [ "list", "watch" ]
+Expand to see example
apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+name: collector # could be .spec.values.explorer.collector.serviceAccount.name
+subjects:
+- kind: ServiceAccount
+ name: collector # should match .spec.values.explorer.collector.serviceAccount.name
+ namespace: flux-system # should match .spec.values.explorer.collector.serviceAccount.namespace
+roleRef:
+kind: ClusterRole
+name: collector # name of the cluster role created earlier
+apiGroup: rbac.authorization.k8s.io
+If you want the collector to watch a particular namespace use a RoleBinding instead.
Expand to see example
apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+name: clusters-service-impersonator-role
+rules:
+- apiGroups: [""]
+ resources: ["users", "groups"]
+ verbs: ["impersonate"]
+- apiGroups: [ "" ]
+ resources: [ "serviceaccounts" ]
+ verbs: [ "impersonate" ]
+ resourceNames:
+ - "collector" # should match .spec.values.explorer.collector.serviceAccount.name
+Next Steps¶
Getting started ENTERPRISE¶
Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
This guide shows you the basics steps to start using Explorer.
Pre-requisites¶
Before using Explorer, please ensure that:
Setup¶
Explorer is enabled via configuration through the feature flag explorer.enabled that you could configure in your Weave Gitops Enterprise HelmRelease values:
---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+ name: weave-gitops-enterprise
+ namespace: flux-system
+spec:
+ # ... other spec components
+ values:
+ explorer:
+ enabled: true # global enable/disable flag
+ collector:
+ # ServiceAccount that explorer will use to watch clusters for resources
+ serviceAccount:
+ name: "collector"
+ namespace: "flux-system"
+ cleaner:
+ disabled: false
+ enabledFor: # controls which parts of the UI utilize the Explorer UI/Server components
+ - applications
+ - sources
+ - gitopssets
+ - templates
+The enabledFor field will control which parts of the UI utilize the Explorer backend for performant queries. Note that this does not control the collection of these objects, only the presentation of the objects in the UI.
For a complete overview on the configuration you could see configuration.
Explorer UI¶
Login to Weave Gitops and Explorer will be shown in the navigation menu Explorer.
Explorer UI looks as follows:
It has two main components:
For a more detailed view on the UI you could see querying.
Explorer ENTERPRISE¶
Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
As platform engineer or as developer, your applications and platform services will likely span multiple kubernetes clusters or infrastructure components. In order to manage and operate them you require a platform capability that allows you to discover the resources from a single place.
Explorer is that capability that allows any platform user to discover platform resources from a single place across all your kubernetes clusters.
FAQ¶
Which journeys would be able to use explorer for?¶
Explorer is better suited for journeys matching the discovery of resources across the platform resources inventory.
Which journeys would be better using other weave gitops capabilities for?¶
If you have a particular resources you want to manage, weave gitops offers single resource experience for almost every resource.
Which Kinds does explorer support?¶
Explorer support all Flux Applications and Sources CRDs
See Supported Kinds for more details.
Next Steps¶
Now that you know what Explorer is, follow getting started to quickly have a feeling of what Explorer can do for you.
Operations ENTERPRISE¶
Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
As platform engineer you could need to have a finer understanding on the underlying logic for Explorer. The following options are available to you to operate and troubleshoot it.
Debug Access Rules¶
It is a debugging tool to make visible explorer authorization logic. You could find it as tab Access Rules alongside the Query tab.
You could discover by Cluster and Subject the Kinds it is allowed to read. These are the rules that will be the source of truth doing authorization when a user does a query.
Monitoring¶
Explorer provides the following telemetry to use for operations.
Metrics¶
Explorer exports Prometheus metrics. See setup to get started.
Querying¶
Explorer querying path is composed of three components exporting metrics:
API Server¶
Based on go-http-metrics, the following metrics are generated.
Request Duration: histogram with the latency of the HTTP requests.
http_request_duration_seconds_bucket{handler="/v1/query",method="POST",le="0.05"} 0
+http_request_duration_seconds_sum{handler="/v1/query",method="POST"} 10.088081923
+http_request_duration_seconds_count{handler="/v1/query",method="POST"} 51
+Response Size: histogram with the size of the HTTP responses in bytes
http_response_size_bytes_bucket{handler="/v1/query",method="POST",le="0.05"} 10
+http_response_size_bytes_sum{handler="/v1/query",method="POST"} 120
+http_response_size_bytes_count{handler="/v1/query",method="POST"} 10
+Requests In Flight: gauge with the number of inflight requests being handled at the same time.
http_requests_inflight{handler="/v1/query"} 0
+Datastore Reads¶
Request Latency: histogram with the latency of the datastore read requests.
datastore_latency_seconds_bucket{action="GetObjectByID", le="+Inf", status="success"} 1175
+datastore_latency_seconds_bucket{action="GetObjectByID", le="0.01", status="success"} 1174
+datastore_latency_seconds_count{action="GetObjectByID", status="success"} 1175
+datastore_latency_seconds_count{action="GetRoleBindings", status="success"} 47
+datastore_latency_seconds_count{action="GetRoles", status="success"} 47
+datastore_latency_seconds_sum{action="GetObjectByID", status="success"} 0.6924557999999995
+datastore_latency_seconds_sum{action="GetRoleBindings", status="success"} 1.329158916
+datastore_latency_seconds_sum{action="GetRoles", status="success"} 3.942473879999999
+Requests In Flight: gauge with the number of inflight requests being handled at the same time.
datastore_inflight_requests{action="GetObjectByID"} 0
+datastore_inflight_requests{action="GetRoleBindings"} 0
+datastore_inflight_requests{action="GetRoles"} 0
+Indexer Reads¶
Request Latency: histogram with the latency of the indexer read requests.
indexer_latency_seconds_bucket{action="ListFacets", le="+Inf", status="success"} 1
+indexer_latency_seconds_bucket{action="Search", le="+Inf", status="success"} 47
+indexer_latency_seconds_sum{action="ListFacets", status="success"} 0.008928666
+indexer_latency_seconds_sum{action="Search", status="success"} 0.06231312599999999
+indexer_latency_seconds_count{action="ListFacets", status="success"} 1
+indexer_latency_seconds_count{action="Search", status="success"} 47
+Requests In Flight: gauge with the number of inflight requests being handled at the same time.
indexer_inflight_requests{action="ListFacets"} 0
+indexer_inflight_requests{action="Search"} 0
+Collecting¶
Explorer collecting path is composed of three components exporting metrics:
The following metrics are available to monitor its health.
Cluster Watcher¶
The metric collector_cluster_watcher provides the number of the cluster watchers it the following status: - Starting: a cluster watcher is starting at the back of detecting that a new cluster has been registered. - Started: cluster watcher has been started and collecting events from the remote cluster. This is the stable state. - Stopping: a cluster has been deregistered so its cluster watcher is no longer required. In the process of stopping it. - Failed: a cluster watcher has failed during the creation or starting process and cannot collect events from the remote clusters. This is the unstable state.
Where collector is the type of collector, it could be - rbac: for collecting RBAC resources (ie roles) - objects: for collecting non-rbac resources (ie kustomizations)
collector_cluster_watcher{collector="objects", status="started"} 1
+collector_cluster_watcher{collector="objects", status="starting"} 0
+collector_cluster_watcher{collector="rbac", status="started"} 1
+collector_cluster_watcher{collector="rbac", status="starting"} 0
+A sum on collector_cluster_watcher gives the total number of cluster watchers that should be equal to the number of clusters
Datastore Writes¶
Request Latency: histogram with the latency of the datastore write requests.
datastore_latency_seconds_bucket{action="StoreRoles", le="+Inf", status="success"} 1175
+datastore_latency_seconds_bucket{action="StoreRoles", le="0.01", status="success"} 1174
+datastore_latency_seconds_count{action="StoreRoles", status="success"} 1175
+datastore_latency_seconds_count{action="DeleteRoles", status="success"} 47
+datastore_latency_seconds_count{action="DeleteAllRoleBindings", status="success"} 47
+datastore_latency_seconds_sum{action="StoreRoles", status="success"} 0.6924557999999995
+datastore_latency_seconds_sum{action="DeleteRoles", status="success"} 1.329158916
+datastore_latency_seconds_sum{action="DeleteAllRoleBindings", status="success"} 3.942473879999999
+Requests In Flight: gauge with the number of inflight write requests being handled at the same time.
datastore_inflight_requests{action="StoreRoles"} 0
+datastore_inflight_requests{action="StoreRoleBindings"} 0
+datastore_inflight_requests{action="DeleteAllRoleBindings"} 0
+Indexer Writes¶
Request Latency: histogram with the latency of the indexer write requests.
indexer_latency_seconds_bucket{action="Add",status="success",le="+Inf"} 109
+indexer_latency_seconds_bucket{action="Remove",status="success",le="+Inf"} 3
+indexer_latency_seconds_sum{action="Add",status="success"} 8.393912168
+indexer_latency_seconds_sum{action="Remove",status="success"} 0.012298476
+indexer_latency_seconds_count{action="Add",status="success"} 109
+indexer_latency_seconds_count{action="Remove",status="success"} 3
+Requests In Flight: gauge with the number of inflight requests being handled at the same time.
indexer_inflight_requests{action="Add"} 0
+indexer_inflight_requests{action="Remove"} 0
+Dashboard¶
Use Explorer dashboard to monitor its golden signals
Explorer dashboard is part of Weave GitOps Dashboards
Querying ENTERPRISE¶
Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
Explorer recommended way to discover resources is via its search dialog. This guide provides the background to understand it and set how to use it.
Schema¶
Every resource is normalised to the following common schema:
| Key | Description |
|---|---|
| Cluster | Name of cluster where the resource exists. As gitops cluster <GitopsClusterNamespace,GitopsClusterName> |
| Namespace | Namespace name where the resource exists. |
| Kind | Resource kubernetes type or kind |
| Name | Resource name as specified in its manifest. |
| Status | Resource health status. Indicates the status of its reconciliation. |
| Message | Resource health status message. It extends status field with information about the status. |
For a podinfo helm release from a cluster default/progress-delivery-demo2-32 like this:
apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+ name: podinfo
+ namespace: flux-system
+spec:
+ chart:
+ spec:
+ chart: podinfo
+ interval: 1m
+ reconcileStrategy: ChartVersion
+ sourceRef:
+ kind: HelmRepository
+ name: podinfo
+ version: 6.0.0
+ interval: 1m
+status:
+ conditions:
+ - message: Release reconciliation succeeded
+ reason: ReconciliationSucceeded
+ status: "True"
+ type: Ready
+The schema looks like
| Cluster | Namespace | Kind | Name | Status | Message |
|---|---|---|---|---|---|
default/progress-delivery-demo2-32 | flux-system | HelmRelease | podinfo | Success | Release reconciliation succeeded |
You can open the query filter settings by clicking on the filter button:
Filtering and Searching¶
The Search field allows for free-form text entry to query objects across all fields. For example, if we enter the term "podinfo", we will get matches for not only object names, but also strings from the Message field:
To filter the results by cluster, kind, namespace, enable the checkbox filters:
Note that the free-form terms only apply to the filtered results from the kind filter. In this case, we only match the "podinfo" string on results that are Kustomizations.
We can also "OR" filters together. Note that filters within a category are OR'd together, but terms are AND'd across categories. For example, selecting the Kind=Kustomization and Kind=HelmRelease filters will show both Kustomizations and HelmReleases:
Feedback & Telemetry
Feedback¶
We ❤️ your comments and suggestions as we look to make successfully adopting a cloud-native approach, to application deployment on Kubernetes with GitOps, easier and easier. There are a number of ways you can reach out:
Anonymous Aggregate User Behavior Analytics¶
Weaveworks is utilizing Pendo, a product-analytics app, to gather anonymous user behavior analytics for both Weave GitOps and Weave GitOps Enterprise. We use this data so we can understand what you love about Weave GitOps, and areas we can improve.
Weave GitOps OSS users will be notified when you create the dashboard for the first time via gitops create dashboard or when you use gitops run for the first time and decide to install the dashboard via that functionality. Analytics will not be enabled until after this notification so that you can opt out before sending analytics data.
For Weave GitOps Enterprise users, this functionality is turned on by default. Further below we go into more detail about how you can control this functionality.
Why are we collecting this data?¶
We want to ensure that we are designing the best features, addressing the most pressing bugs, and prioritizing our roadmap appropriately for our users. Collecting analytics on our users’ behaviors gives us valuable insights and allows us to conduct analyses on user behavior within the product. This is important for us so we can make informed decisions- based on how, where and when our users use Weave GitOps - and prioritize what is most important to users like you.
For example¶
We’d like to understand the usage of the graph and dependency tabs within the dashboard. If users are utilizing this feature, we would like to understand the value and how we can improve that feature. However, if users aren’t using it, we can conduct research to understand why and either fix it, or come to the conclusion that it really doesn’t serve any utility and focus our efforts on more valuable features.
How long is the collected data stored?¶
Weave GitOps’s anonymous user and event data has a 24 month retention policy. The default value for data retention in Pendo is 7 years. For more information on Pendo’s data storage policies, click here.
What are we collecting?¶
Weave GitOps gathers data on how the CLI and Web UI are used. There is no way for us or Pendo to connect our IDs to individual users or sites.
For the CLI, we gather usage data on:
For the Web UI, we gather usage data on:
When is the data collected and where is it sent?¶
Weave GitOps CLI analytics are sent at startup. The dashboard analytics are sent through its execution. Both CLI and Dashboard analytics are sent to Pendo over HTTPS.
How?¶
The CLI code is viewable in pkg/analytics. It will ignore any errors, e.g. if you don’t have any network connection.
The dashboard setup code is viewable in ui/components/Pendo.tsx - this will fetch a 3rd party javascript from Pendo’s servers.
Opting out¶
All the data collected, analytics, and feedback are for the sole purpose of creating better product experience for you and your teams. We would really appreciate it if you left the analytics on as it helps us prioritize which features to build next and what features to improve. However, if you do want to opt out of Weave GitOps’s analytics you can opt out of CLI and/or Dashboard analytics.
CLI¶
We have created a command to make it easy to turn analytics on or off for the CLI.
To disable analytics: gitops set config analytics false
To enable analytics: gitops set config analytics true
Dashboard¶
You need to update your helm release to remove WEAVE_GITOPS_FEATURE_TELEMETRY from the envVars value.
Annotations ENTERPRISE¶
The add-common-bases annotation¶
The templates.weave.works/add-common-bases: "true" annotation can be used to enable and disable the addition of a "common bases" Kustomization to the list of rendered files. This kustomization will sync a path that is common to all clusters (clusters/bases).
An example usecase would be to ensure that certain RBAC or policies are applied to all clusters using this template.
The inject-prune-annotation annotation¶
The templates.weave.works/inject-prune-annotation: "true" annotation can be used to enable and disable the injection of Flux's prune annotation into certain resources.
When enabled, GitOps automatically injects a kustomize.toolkit.fluxcd.io/prune: disabled annotation into every resource in the spec.resourcetemplates that is not a cluster.x-k8s.io.Cluster and not a gitops.weave.works.GitopsCluster.
The intention here is stop Flux from explicitly deleting subresources of the Cluster like AWSCluster, KubeadmControlPlane, AWSMachineTemplate etc and let the CAPI controllers handle their removal.
This is the pattern recommended in the capi-quickstart guide https://cluster-api.sigs.k8s.io/user/quick-start.html#clean-up.
Template CLI ENTERPRISE¶
The Enterprise gitops CLI tool provides a set of commands to help you manage your templates.
Here we're going to talk about the gitops create template command that allows you to render templates locally and airgapped, without a full WGE installation in a Kubernetes cluster.
Use cases¶
Restrictions¶
The gitops create template command only works with GitOpsTemplate objects. It does not work with CAPITemplate objects. You should be able to migrate any CAPITemplate objects to GitOpsTemplate with some small tweaks.
Info
GitOpsTemplate or CAPITemplate?
The only difference between CAPITemplate and GitOpsTemplate is the default value of these two annotations:
| Annotation | default value for CAPITemplate | default value for GitOpsTemplate |
|---|---|---|
templates.weave.works/add-common-bases | "true" | "false" |
templates.weave.works/inject-prune-annotations | "true" | "false" |
Installation¶
See the Weave Gitops Enterprise installation instructions for details on how to install the EE gitops CLI tool.
Getting started¶
Using a local GitOpsTemplate manifest with required parameters exported in the environment, the command can render the template to one of the following: 1. The current kubecontext directly (default) 1. stdout with --export 1. The local file system with --output-dir, this will use the spec.resourcestemplates[].path fields in the template to determine where to write the rendered files. This is the recommended approach for GitOps as you can then commit the rendered files to your repository.
gitops create template \
+ --template-file capd-template.yaml \
+ --output-dir ./clusters/ \
+ --values CLUSTER_NAME=foo
+Profiles¶
As in the UI you can add profiles to your template. However instead of reading the latest version of a profile and its layers from a HelmRepository object in the cluster, we instead read from your local helm cache.
helm repo add weaveworks-charts https://raw.githubusercontent.com/weaveworks/weave-gitops-profile-examples/gh-pages
+helm repo update
+This particular helm repo provides a version of the cert-manager repo and others.
Supplying values to a profile¶
You can supply a values.yaml file to a profile using the values parameter. For example we can supply cert-manager's values.yaml with:
gitops create template \
+ --template-file capd-template.yaml \
+ --output-dir ./out \
+ --values CLUSTER_NAME=foo \
+ --profiles "name=cert-manager,namespace=foo,version=>0.1,values=cert-manager-values.yaml"
+Using a config file¶
Instead of specifying the parameters on the command line you can supply a config file. For example the above invocation can be replaced like so:
```yaml title=config.yaml template-file: capd-capi-template.yaml output-dir: ./out values: - CLUSTER_NAME=foo profiles: - name=cert-manager,namespace=foo,version=>0.1,values=cert-manager-values.yaml
and executed with:
+
+```bash
+gitops create template --config config.yaml
+CAPI Cluster Template Example ENTERPRISE¶
GitOps template objects need to be wrapped with the GitOpsTemplate custom resource and then loaded into the management cluster.
apiVersion: templates.weave.works/v1alpha2
+kind: GitOpsTemplate
+metadata:
+ name: cluster-template-development
+ labels:
+ weave.works/template-type: cluster
+spec:
+ description: This is the std. CAPD template
+ renderType: templating
+ params:
+ - name: CLUSTER_NAME
+ description: This is used for the cluster naming.
+ resourcetemplates:
+ - apiVersion: cluster.x-k8s.io/v1alpha3
+ kind: Cluster
+ metadata:
+ name: "{{ .params.CLUSTER_NAME }}"
+Creating GitOpsTemplates ENTERPRISE¶
Tip
For complete examples of widely-used templates, see the Quickstart guide.
GitOps Templates were originally introduced to enable self-service operations for the the cluster creation workflow.
We have since extended this capability to cover Terraform, Crossplane and general Kubernetes resources.
An example template could, upon merging to a GitOps repository and reconciling in a cluster, provide a running developer environment consisting of an EKS cluster, an RDS database, and a branch and revision of the current application through single template.
Templates can be loaded into the cluster by Platform Operator by adding them to the Flux-manage GitOps repository for the target cluster. Alternatively, they can be applied directly to the cluster with kubectl.
Info
Weave GitOps will search for templates in the default namespace. This can be changed by configuring the config.capi.namespace value in the Weave GitOps Enterprise Helm Chart.
Template Type¶
Template types are used by Weave GitOps to group the templates nicely in the Dashboard UI.
There are 4 recommended template types:
Declare this in the object manifest by using the weave.works/template-type label and setting the value as the name of the type.
---
+apiVersion: templates.weave.works/v1alpha2
+kind: GitOpsTemplate
+metadata:
+ name: example-template
+ namespace: default
+ labels:
+ weave.works/template-type: pipeline
+spec:
+# ...
+Template Components¶
The rendering of certain component sections in a template can be enabled or disabled with annotations. The annotation keys are of the form templates.weave.works/COMPONENT-enabled and have boolean values.
Supported components:
Example:
annotations:
+ templates.weave.works/profiles-enabled: "true"
+ templates.weave.works/kustomizations-enabled: "false"
+ templates.weave.works/credentials-enabled: "true"
+In-UI Template Editing¶
When rendering a template, a templates.weave.works/create-request annotation is added by default to the first resource in the resourcetemplates.
It can be added to any other resource by simply adding the annotation in empty form. This annotation holds information about which template generated the resource and the parameter values used as a json string.
If the resource type is one of the following and has this annotation, an Edit resource button will appear in the GitOps UI which allows the editing of the resource by users, after which it will be re-rendered:
Example:
spec:
+ resourcetemplates:
+ - apiVersion: v1
+ kind: ConfigMap
+ metadata:
+ name: my-configmap
+ data:
+ my-key: my-value
+ - apiVersion: source.toolkit.fluxcd.io/v1beta1
+ kind: HelmRepository
+ metadata:
+ # This annotation will add an `Edit resource` button in the UI for this resource
+ annotations:
+ templates.weave.works/create-request: ''
+ name: nginx
+ namespace: default
+Introduction ENTERPRISE¶
A GitOpsTemplate enables application developers to self-service components and services easily through the Weave GitOps Dashboard. It's a simple YAML file that you can enrich with parameters, variables, metadata, and conditions.
Use a GitOpsTemplate to template any resource that can be expressed in YAML (basic Kubernetes resources, Flux primitives, Terraform controller, Crossplane, Cluster API, etc.) into a standardised definition.
Application developers can use a template through our GUI. The rendered template is added to their GitOps repository via a pull request. When merged and reconciled, the resources in the template are created. A resource can be a MachinePool for CAPI objects, a Flux Kustomization, or a Terraform Controller resource, to name a few examples.
Tip
A GitOpsTemplate must be valid yaml. Beyond this, a rendered template can create any resource you need 
.
Info
GitOpsTemplate or CAPITemplate?
The only difference between CAPITemplate and GitOpsTemplate is the default value of these two annotations:
| Annotation | default value for CAPITemplate | default value for GitOpsTemplate |
|---|---|---|
templates.weave.works/add-common-bases | "true" | "false" |
templates.weave.works/inject-prune-annotations | "true" | "false" |
Parameters ENTERPRISE¶
When users have chosen a template, they will be presented with a form to complete.
This form will collect the specific resource configuration which they would like applied to their instance.
Resource variables, or parameters, are set by the template author in the template object manifest under spec.params.
Required params¶
Some params are required for all resources as they will be used to generate paths for the eventually rendered resources.
These are: - CLUSTER_NAME - RESOURCE_NAME
Parameters metadata¶
The following metadata fields can be added for each parameter under spec.params. These will get rendered nicely in the UI form allowing users to understand what each field is for.
Example:
spec:
+ params:
+ - name: IP_ADDRESS
+ description: 'The IP address of this service'
+ options: [1.2.3.4, 5.6.7.8]
+ default: 1.2.3.4
+Adding Profiles to Templates ENTERPRISE¶
Profiles are enhanched Helm Charts which allow operators to make additional components either optional or required to developers using self-service templates.
Default and required profiles can be added via the template spec.charts section.
spec:
+ charts:
+ items:
+ - name: nginx
+ version: 1.0.0
+ targetNamespace: nginx
+ - name: cert-manager
+ targetNamespace: cert-manager
+A template with the above profiles would offer Application Developers the option to add nginx and cert-manager resources to their templated resources, ready for deployment to their cluster.
Profile Operator Settings¶
Keys available in the spec.charts section and the template variables available to them.
| Key | Description | Template vars |
|---|---|---|
helmRepositoryTemplate.path | Path the HelmRepository will be written to | params |
items | list of charts to configure, see below |
Keys available in the spec.charts.items entries and the template variables available to them.
| Key | Description | Template vars |
|---|---|---|
template.content | Full or partial HelmRelease CR template | params |
template.path | Path the HelmRelease will be written to | params |
chart | Shortcut to HelmRelease.spec.chart.spec.chart | |
version | Shortcut to HelmRelease.spec.chart.spec.version | |
targetNamespace | Shortcut to HelmRelease.spec.targetNamespace | |
values | Shortcut to HelmRelease.spec.values | params |
layer | Layer to install as | |
required | (default=false) Allow the user to de-select this profile | |
editable | (default=false) Allow the user to edit the values.yaml of this profile |
Expand for a complete yaml example
spec:
+charts:
+ helmRepositoryTemplate:
+ path: clusters/${CLUSTER_NAME}/helm-repositories.yaml
+ items:
+ - chart: cert-manager
+ version: v1.5.3
+ editable: false
+ required: true
+ values:
+ installCRDs: ${CERT_MANAGER_INSTALL_CRDS}
+ targetNamespace: cert-manager
+ layer: layer-1
+ template:
+ path: clusters/${CLUSTER_NAME}/cert-manager.yaml
+ content:
+ metadata:
+ labels:
+ app.kubernetes.io/name: cert-manager
+ spec:
+ retries: ${CERT_MANAGER_RETRY_COUNT}
+Tip
template.content will be merged over the top of a default HelmRelease CR so it does not need to be complete.
Declaring Profiles with Annotations¶
Deprecated feature
Where possible please use the spec.charts section as detailed above to declare profiles.
Profiles can also be included within templates by the capi.weave.works/profile-INDEX annotation.
annotations:
+ capi.weave.works/profile-0: '{"name": "NAME", "version": "VERSION", "editable": EDITABLE, "namespace": "NAMESPACE"}'
+Where:
Quickstart GitOps Templates ENTERPRISE¶
Quickstart templates are GitOpsTemplates that you could use when getting started with Weave Gitops Enterprise It aims to provide a simplified basic experience.
Getting Started¶
The templates exist as a Helm Chart in the weave-gitops-quickstart github repo.
To get started, add the following HelmRelease object to your Weave GitOps Enterprise configuration repo for your management cluster.
Expand to view
---
+apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: GitRepository
+metadata:
+name: weave-gitops-quickstart
+namespace: flux-system
+spec:
+interval: 10m0s
+ref:
+ branch: main
+url: https://github.com/weaveworks/weave-gitops-quickstart
+---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+name: quickstart-templates
+namespace: flux-system
+spec:
+chart:
+ spec:
+ chart: "quickstart-templates"
+ version: ">=0.1.0"
+ sourceRef:
+ kind: GitRepository
+ name: weave-gitops-quickstart
+ namespace: flux-system
+interval: 10m0s
+Commit and merge the above file. Once the HelmRelease has been successfully deployed to your cluster, navigate to your Weave GitOps UI Dashboard. You will see that the templates Chart is now deployed to your cluster.
If you click on the Templates tab in the sidebar, you will see the Quickstart templates are now available for use:
Available Templates¶
The following pipeline templates have been made available on your Weave GitOps Enterprise instance:
Using GitOpsTemplates as a Platform Engineer¶
The above Quickstart templates are designed to provide a practical getting started experience. We encourage Platform Operators to start off with these templates within their team to ramp up on using Weave GitOps.
If the need arises later, operators can always expand on these templates to develop their own set of self-service capabilities.
Using GitOpsTemplates as an Application Developer¶
As a developer using Weave GitOps Enterprise, use the templates to explore GitOps's capabilities. For example, to create a pipeline for your application: use the above template provided by your Operations team to create required resources. Once they have been added to your GitOps repository, you can adapt the rendered resources to meet your needs.
Want to contribute?
The Quickstart templates are maintained by the Weave Gitops team. If you would like to make alterations, suggest fixes, or even contribute a new template which you find cool, just head to the repo and open a new issue or PR!
Rendered Template Paths ENTERPRISE¶
Template authors can configure the eventual locatation of the rendered template in the user's GitOps repository.
This allows for more control over where different resources in the template are rendered.
Configuring Paths¶
The path for rendered resources is configured via the spec.resourcetemplates[].path field.
Important to note
Expand to see example
spec:
+resourcetemplates:
+ // highlight-next-line
+ - path: clusters/${CLUSTER_NAME}/definition/cluster.yaml
+ content:
+ - apiVersion: cluster.x-k8s.io/v1alpha4
+ kind: Cluster
+ metadata:
+ name: ${CLUSTER_NAME}
+ ...
+ - apiVersion: infrastructure.cluster.x-k8s.io/v1alpha4
+ kind: AWSCluster
+ metadata:
+ name: ${CLUSTER_NAME}
+ ...
+ // highlight-next-line
+ - path: clusters/${CLUSTER_NAME}/workloads/helmreleases.yaml
+ content:
+ - apiVersion: helm.toolkit.fluxcd.io/v2beta1
+ kind: HelmRelease
+ metadata:
+ name: ${CLUSTER_NAME}-nginx
+ ...
+ - apiVersion: helm.toolkit.fluxcd.io/v2beta1
+ kind: HelmRelease
+ metadata:
+ name: ${CLUSTER_NAME}-cert-manager
+ ...
+Configuring paths for charts¶
The spec.charts.helmRepositoryTemplate.path and spec.charts.items[].template.path fields can be used to specify the paths of these resources:
Example
spec:
+ charts:
+ helmRepositoryTemplate:
+ // highlight-next-line
+ path: clusters/${CLUSTER_NAME}/workloads/helm-repo.yaml
+ items:
+ - chart: cert-manager
+ version: 0.0.8
+ template:
+ // highlight-next-line
+ path: clusters/${CLUSTER_NAME}/workloads/cert-manager.yaml
+Default Paths¶
If the spec.resourcetemplates[].path is omitted, a default path for the rendered template is calculated.
In this case some of the submitted params are used. Users must provide one of the following parameters: - CLUSTER_NAME - RESOURCE_NAME
To ensure users supply these values, set the parameters to required in the the template definition:
spec:
+ params:
+ - name: RESOURCE_NAME
+ required: true
+ # or
+ - name: CLUSTER_NAME
+ required: true
+Important
The kustomization feature and the add-common-bases annotation feature always use a calculated default path. If you are using these features one of CLUSTER_NAME or RESOURCE_NAME must be provided, even if you specify a path for all the other resources in the template.
The default path for a template has a few components: - From the params: CLUSTER_NAME or RESOURCE_NAME, required. - From the params: NAMESPACE, default: default - From values.yaml for the Weave GitOps Enterprise mccp chart: values.config.capi.repositoryPath, default: clusters/management/clusters
These are composed to create the path: ${repositoryPath}/${NAMESPACE}/${CLUSTER_OR_RESOURCE_NAME}.yaml
Using the default values and supplying CLUSTER_NAME as my-cluster will result in the path: clusters/management/clusters/default/my-cluster.yaml
Resource templates ENTERPRISE¶
Resource templates are used to create Kubernetes resources. They are defined in the spec.resourcetemplates section of the template.
The content key¶
The content key is used to define a list of resources:
spec:
+ resourcetemplates:
+ - content:
+ - apiVersion: v1
+ kind: Namespace
+ metadata:
+ name: nginx
+ - apiVersion: v1
+ kind: Namespace
+ metadata:
+ name: cert-manager
+The raw key¶
The raw key is used to define a raw string that will written to the specified path.
This can be useful to preserve comments or formatting in the rendered resource.
spec:
+ resourcetemplates:
+ - path: "helm-release.yaml"
+ raw: |
+ apiVersion: helm.toolkit.fluxcd.io/v2beta1
+ kind: HelmRelease
+ metadata:
+ name: podinfo
+ namespace: prod-github
+ spec:
+ interval: 1m
+ chart:
+ spec:
+ chart: podinfo
+ version: "6.0.0" # {"$promotion": "flux-system:podinfo-github:prod"}
+ sourceRef:
+ kind: HelmRepository
+ name: podinfo
+ interval: 1m
+Info
Supported Templating Languages ENTERPRISE¶
The following templating languages are supported: - envsubst (default) - templating
Declare the templating language to be used to render the template by setting spec.renderType.
Envsubst¶
envsubst, which is short for 'environment substitution', uses envsubst for rendering. This templating format is used by clusterctl.
Variables can be set for rendering into the template in the ${VAR_NAME} syntax.
Supported Functions¶
| Expression | Meaning |
|---|---|
${var} | Value of $var |
${#var} | String length of $var |
${var^} | Uppercase first character of $var |
${var^^} | Uppercase all characters in $var |
${var,} | Lowercase first character of $var |
${var,,} | Lowercase all characters in $var |
${var:n} | Offset $var n characters from start |
${var:n:len} | Offset $var n characters with max length of len |
${var#pattern} | Strip shortest pattern match from start |
${var##pattern} | Strip longest pattern match from start |
${var%pattern} | Strip shortest pattern match from end |
${var%%pattern} | Strip longest pattern match from end |
${var-default} | If $var is not set, evaluate expression as $default |
${var:-default} | If $var is not set or is empty, evaluate expression as $default |
${var=default} | If $var is not set, evaluate expression as $default |
${var:=default} | If $var is not set or is empty, evaluate expression as $default |
${var/pattern/replacement} | Replace as few pattern matches as possible with replacement |
${var//pattern/replacement} | Replace as many pattern matches as possible with replacement |
${var/#pattern/replacement} | Replace pattern match with replacement from $var start |
${var/%pattern/replacement} | Replace pattern match with replacement from $var end |
Templating¶
Templating uses text/templating for rendering, using go-templating style syntax {{ .params.CLUSTER_NAME }} where params are provided by the .params variable. Template functions can also be used with the syntax {{ .params.CLUSTER_NAME | FUNCTION }}.
Supported Functions¶
As taken (from the Sprig library)
| Function Type | Functions |
|---|---|
| String Functions | trim, wrap, randAlpha, plural |
| String List Functions | splitList, sortAlpha |
| Integer Math Functions | add, max, mul |
| Integer Slice Functions | until, untilStep |
| Float Math Functions | addf, maxf, mulf |
| Date Functions | now, date |
| Defaults Functions | default, empty, coalesce, fromJson, toJson, toPrettyJson, toRawJson, ternary |
| Encoding Functions | b64enc, b64dec |
| Lists and List Functions | list, first, uniq |
| Dictionaries and Dict Functions | get, set, dict, hasKey, pluck, dig, deepCopy |
| Type Conversion Functions | atoi, int64, toString |
| Flow Control Functions | fail |
| UUID Functions | uuidv4 |
| Version Comparison Functions | semver, semverCompare |
| Reflection | typeOf, kindIs, typeIsLike |
Custom Delimiters¶
The default delimiters for renderType: templating are {{ and }}. These can be changed by setting the templates.weave.works/delimiters annotation on the template. For example:
Version Information ENTERPRISE¶
There are now multiple published versions of the template CRD.
Migration notes¶
v1alpha1 to v1alpha2¶
When manually migrating a template from v1alpha1 to v1alpha2 (for example in git) you will need to: 1. Update the apiVersion: 1. for GitopsTemplate update the apiVersion to templates.weave.works/v1alpha2 1. for CAPITemplate update the apiVersion to capi.weave.works/v1alpha2 1. Move the spec.resourcetemplates field to spec.resourcetemplates[0].content 1. Either leave the spec.resourcetemplates[0].path field empty or give it a sensible value.
If you experience issues with the path not being recognised when Flux reconciles the new template versions, try manually applying the new template to the cluster directly with: 1. Run kubectl apply -f capi-template.yaml 1. Run flux reconcile kustomization --with-source flux-system twice.
Conversion Webhook¶
As of Weave Gitops Enterprise 0.28.0 the conversion webhook has been removed.
This removed the need for cert-manager to be installed, but you will now have to convert any v1alpha1 templates to v1alpha2 manually in git.
v1alpha2 (default) notes¶
This version changes the type of spec.resourcetemplates from a list of objects to a list of files with a path and content:
Example:
spec:
+ resourcetemplates:
+ - path: "clusters/{{ .params.CLUSTER_NAME }}.yaml"
+ content:
+ - apiVersion: cluster.x-k8s.io/v1alpha3
+ kind: Cluster
+ metadata:
+ name: "{{ .params.CLUSTER_NAME }}"
+ path: "clusters/{{ .params.CLUSTER_NAME }}.yaml"
+v1alpha1 notes¶
The original version of the template. This version no longer works with Weave Gitops Enterprise 0.28.0 and above.
It uses spec.resourcetemplates as a list of resources to render.
Example:
spec:
+ resourcetemplates:
+ - apiVersion: cluster.x-k8s.io/v1alpha3
+ kind: Cluster
+ metadata:
+ name: "{{ .params.CLUSTER_NAME }}"
+Packages:
+ +templates.weave.works/v1alpha1
+Package v1alpha1 contains API Schema definitions for the gitopssets v1alpha1 API group
+Resource Types: +GitOpsSet +
+GitOpsSet is the Schema for the gitopssets API
+| Field | +Description | +||||||||
|---|---|---|---|---|---|---|---|---|---|
+apiVersion+string |
+
+templates.weave.works/v1alpha1
+ |
+||||||||
+kind+string + |
+
+GitOpsSet
+ |
+||||||||
+metadata+ + +Kubernetes meta/v1.ObjectMeta + + + |
+
+Refer to the Kubernetes API documentation for the fields of the
+metadata field.
+ |
+||||||||
+spec+ + +GitOpsSetSpec + + + |
+
+ + +
|
+||||||||
+status+ + +GitOpsSetStatus + + + |
++ | +
APIClientGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+APIClientGenerator defines a generator that queries an API endpoint and uses +that to generate data.
+| Field | +Description | +
|---|---|
+interval+ + +Kubernetes meta/v1.Duration + + + |
+
+ The interval at which to poll the API endpoint. + |
+
+endpoint+ +string + + |
+
+(Optional)
+ This is the API endpoint to use. + |
+
+method+ +string + + |
+
+ Method defines the HTTP method to use to talk to the endpoint. + |
+
+jsonPath+ +string + + |
+
+ JSONPath is string that is used to modify the result of the API +call. +This can be used to extract a repeating element from a response. +https://kubernetes.io/docs/reference/kubectl/jsonpath/ + |
+
+headersRef+ + +HeadersReference + + + |
+
+(Optional)
+ HeadersRef allows optional configuration of a Secret or ConfigMap to add +additional headers to an outgoing request. +For example, a Secret with a key Authorization: Bearer abc123 could be +used to configure an authorization header. + |
+
+body+ + +Kubernetes pkg/apis/apiextensions/v1.JSON + + + |
+
+(Optional)
+ Body is set as the body in a POST request. +If set, this will configure the Method to be POST automatically. + |
+
+singleElement+ +bool + + |
+
+(Optional)
+ SingleElement means generate a single element with the result of the API +call. +When true, the response must be a JSON object and will be returned as a +single element, i.e. only one element will be generated containing the +entire object. + |
+
+secretRef+ + +Kubernetes core/v1.LocalObjectReference + + + |
+
+ Reference to Secret in same namespace with a field “caFile” which +provides the Certificate Authority to trust when making API calls. + |
+
ClusterGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+ClusterGenerator defines a generator that queries the cluster API for +relevant clusters.
+| Field | +Description | +
|---|---|
+selector+ + +Kubernetes meta/v1.LabelSelector + + + |
+
+(Optional)
+ Selector is used to filter the clusters that you want to target. +If no selector is provided, no clusters will be matched. + |
+
ConfigGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+ConfigGenerator loads a referenced ConfigMap or +Secret from the Cluster and makes it available as a resource.
+| Field | +Description | +
|---|---|
+kind+ +string + + |
+
+ Kind of the referent. + |
+
+name+ +string + + |
+
+ Name of the referent. + |
+
GitOpsSetGenerator +
++(Appears on: +GitOpsSetSpec) +
+GitOpsSetGenerator is the top-level set of generators for this GitOpsSet.
+| Field | +Description | +
|---|---|
+list+ + +ListGenerator + + + |
++ | +
+pullRequests+ + +PullRequestGenerator + + + |
++ | +
+gitRepository+ + +GitRepositoryGenerator + + + |
++ | +
+ociRepository+ + +OCIRepositoryGenerator + + + |
++ | +
+matrix+ + +MatrixGenerator + + + |
++ | +
+cluster+ + +ClusterGenerator + + + |
++ | +
+apiClient+ + +APIClientGenerator + + + |
++ | +
+imagePolicy+ + +ImagePolicyGenerator + + + |
++ | +
+config+ + +ConfigGenerator + + + |
++ | +
GitOpsSetNestedGenerator +
++(Appears on: +MatrixGenerator) +
+GitOpsSetNestedGenerator describes the generators usable by the MatrixGenerator. +This is a subset of the generators allowed by the GitOpsSetGenerator because the CRD format doesn’t support recursive declarations.
+| Field | +Description | +
|---|---|
+name+ +string + + |
+
+(Optional)
+ Name is an optional field that will be used to prefix the values generated +by the nested generators, this allows multiple generators of the same +type in a single Matrix generator. + |
+
+list+ + +ListGenerator + + + |
++ | +
+gitRepository+ + +GitRepositoryGenerator + + + |
++ | +
+ociRepository+ + +OCIRepositoryGenerator + + + |
++ | +
+pullRequests+ + +PullRequestGenerator + + + |
++ | +
+cluster+ + +ClusterGenerator + + + |
++ | +
+apiClient+ + +APIClientGenerator + + + |
++ | +
+imagePolicy+ + +ImagePolicyGenerator + + + |
++ | +
+config+ + +ConfigGenerator + + + |
++ | +
GitOpsSetSpec +
++(Appears on: +GitOpsSet) +
+GitOpsSetSpec defines the desired state of GitOpsSet
+| Field | +Description | +
|---|---|
+suspend+ +bool + + |
+
+(Optional)
+ Suspend tells the controller to suspend the reconciliation of this +GitOpsSet. + |
+
+generators+ + +[]GitOpsSetGenerator + + + |
+
+ Generators generate the data to be inserted into the provided templates. + |
+
+templates+ + +[]GitOpsSetTemplate + + + |
+
+ Templates are a set of YAML templates that are rendered into resources +from the data supplied by the generators. + |
+
+serviceAccountName+ +string + + |
+
+(Optional)
+ The name of the Kubernetes service account to impersonate +when reconciling this Kustomization. + |
+
GitOpsSetStatus +
++(Appears on: +GitOpsSet) +
+GitOpsSetStatus defines the observed state of GitOpsSet
+| Field | +Description | +
|---|---|
+ReconcileRequestStatus+ + +github.com/fluxcd/pkg/apis/meta.ReconcileRequestStatus + + + |
+
+
+(Members of |
+
+observedGeneration+ +int64 + + |
+
+(Optional)
+ ObservedGeneration is the last observed generation of the HelmRepository +object. + |
+
+conditions+ + +[]Kubernetes meta/v1.Condition + + + |
+
+(Optional)
+ Conditions holds the conditions for the GitOpsSet + |
+
+inventory+ + +ResourceInventory + + + |
+
+(Optional)
+ Inventory contains the list of Kubernetes resource object references that +have been successfully applied + |
+
GitOpsSetTemplate +
++(Appears on: +GitOpsSetSpec) +
+GitOpsSetTemplate describes a resource to create
+| Field | +Description | +
|---|---|
+repeat+ +string + + |
+
+ Repeat is a JSONPath string defining that the template content should be +repeated for each of the matching elements in the JSONPath expression. +https://kubernetes.io/docs/reference/kubectl/jsonpath/ + |
+
+content+ + +k8s.io/apimachinery/pkg/runtime.RawExtension + + + |
+
+ Content is the YAML to be templated and generated. + |
+
GitRepositoryGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+GitRepositoryGenerator generates from files in a Flux GitRepository resource.
+| Field | +Description | +
|---|---|
+repositoryRef+ +string + + |
+
+ RepositoryRef is the name of a GitRepository resource to be generated from. + |
+
+files+ + +[]RepositoryGeneratorFileItem + + + |
+
+ Files is a set of rules for identifying files to be parsed. + |
+
+directories+ + +[]RepositoryGeneratorDirectoryItem + + + |
+
+ Directories is a set of rules for identifying directories to be +generated. + |
+
HeadersReference +
++(Appears on: +APIClientGenerator) +
+HeadersReference references either a Secret or ConfigMap to be used for +additional request headers.
+| Field | +Description | +
|---|---|
+kind+ +string + + |
+
+ The resource kind to get headers from. + |
+
+name+ +string + + |
+
+ Name of the resource in the same namespace to apply headers from. + |
+
ImagePolicyGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+ImagePolicyGenerator generates from the ImagePolicy.
+| Field | +Description | +
|---|---|
+policyRef+ +string + + |
+
+ PolicyRef is the name of a ImagePolicy resource to be generated from. + |
+
ListGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+ListGenerator generates from a hard-coded list.
+| Field | +Description | +
|---|---|
+elements+ + +[]Kubernetes pkg/apis/apiextensions/v1.JSON + + + |
++ | +
MatrixGenerator +
++(Appears on: +GitOpsSetGenerator) +
+MatrixGenerator defines a matrix that combines generators. +The matrix is a cartesian product of the generators.
+| Field | +Description | +
|---|---|
+generators+ + +[]GitOpsSetNestedGenerator + + + |
+
+ Generators is a list of generators to be combined. + |
+
+singleElement+ +bool + + |
+
+(Optional)
+ SingleElement means generate a single element with the result of the +merged generator elements. +When true, the matrix elements will be merged to a single element, with +whatever prefixes they have. +It’s recommended that you use the Name field to separate out elements. + |
+
OCIRepositoryGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+OCIRepositoryGenerator generates from files in a Flux OCIRepository resource.
+| Field | +Description | +
|---|---|
+repositoryRef+ +string + + |
+
+ RepositoryRef is the name of a OCIRepository resource to be generated from. + |
+
+files+ + +[]RepositoryGeneratorFileItem + + + |
+
+ Files is a set of rules for identifying files to be parsed. + |
+
+directories+ + +[]RepositoryGeneratorDirectoryItem + + + |
+
+ Directories is a set of rules for identifying directories to be +generated. + |
+
PullRequestGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+PullRequestGenerator defines a generator that queries a Git hosting service +for relevant PRs.
+| Field | +Description | +
|---|---|
+interval+ + +Kubernetes meta/v1.Duration + + + |
+
+ The interval at which to check for repository updates. + |
+
+driver+ +string + + |
+
+ Determines which git-api protocol to use. + |
+
+serverURL+ +string + + |
+
+(Optional)
+ This is the API endpoint to use. + |
+
+repo+ +string + + |
+
+ This should be the Repo you want to query. +e.g. my-org/my-repo + |
+
+secretRef+ + +Kubernetes core/v1.LocalObjectReference + + + |
+
+ Reference to Secret in same namespace with a field “password” which is an +auth token that can query the Git Provider API. + |
+
+labels+ +[]string + + |
+
+(Optional)
+ Labels is used to filter the PRs that you want to target. +This may be applied on the server. + |
+
+forks+ +bool + + |
+
+(Optional)
+ Fork is used to filter out forks from the target PRs if false, +or to include forks if true + |
+
RepositoryGeneratorDirectoryItem +
++(Appears on: +GitRepositoryGenerator, +OCIRepositoryGenerator) +
+RepositoryGeneratorDirectoryItem stores the information about a specific +directory to be generated from.
+| Field | +Description | +
|---|---|
+path+ +string + + |
++ | +
+exclude+ +bool + + |
++ | +
RepositoryGeneratorFileItem +
++(Appears on: +GitRepositoryGenerator, +OCIRepositoryGenerator) +
+RepositoryGeneratorFileItem defines a path to a file to be parsed when generating.
+| Field | +Description | +
|---|---|
+path+ +string + + |
+
+ Path is the name of a file to read and generate from can be JSON or YAML. + |
+
ResourceInventory +
++(Appears on: +GitOpsSetStatus) +
+ResourceInventory contains a list of Kubernetes resource object references that have been applied by a Kustomization.
+| Field | +Description | +
|---|---|
+entries+ + +[]ResourceRef + + + |
+
+ Entries of Kubernetes resource object references. + |
+
ResourceRef +
++(Appears on: +ResourceInventory) +
+ResourceRef contains the information necessary to locate a resource within a cluster.
+| Field | +Description | +
|---|---|
+id+ +string + + |
+
+ ID is the string representation of the Kubernetes resource object’s metadata, +in the format ‘namespace_name_group_kind’. + |
+
+v+ +string + + |
+
+ Version is the API version of the Kubernetes resource object’s kind. + |
+
+
diff --git a/userdocs/site/gitopssets/gitopssets-api-reference/index.html b/userdocs/site/gitopssets/gitopssets-api-reference/index.html
new file mode 100644
index 0000000000..306c016f4a
--- /dev/null
+++ b/userdocs/site/gitopssets/gitopssets-api-reference/index.html
@@ -0,0 +1,12 @@
+ This page was automatically generated with gen-crd-api-reference-docs
Installation ENTERPRISE¶
The gitopssets-controller can be installed in two ways:
The standalone installation can be useful for leaf clusters that don't have Weave GitOps Enterprise installed.
Prerequisites¶
Before installing the gitopssets-controller, ensure that you've installed Flux.
Installing the gitopssets-controller¶
To install the gitopssets-controller using a Helm chart, use the following HelmRelease:
apiVersion: v1
+kind: Namespace
+metadata:
+ name: gitopssets-system
+---
+apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: HelmRepository
+metadata:
+ name: weaveworks-oci-charts
+ namespace: gitopssets-system
+spec:
+ interval: 1m
+ type: oci
+ url: oci://ghcr.io/weaveworks/charts
+---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+ name: gitopssets-controller
+ namespace: gitopssets-system
+spec:
+ interval: 10m
+ chart:
+ spec:
+ chart: gitopssets-controller
+ sourceRef:
+ kind: HelmRepository
+ name: weaveworks-oci-charts
+ namespace: gitopssets-system
+ version: 0.15.3
+ install:
+ crds: CreateReplace
+ upgrade:
+ crds: CreateReplace
+After adding the Namespace, HelmRepository and HelmRelease to a Git repository synced by Flux, commit the changes to complete the installation process.
Customising the Generators¶
Not all generators are enabled by default, this is because not all CRDs are required by the generators.
You might want to enable or disable individual generators via the Helm Chart:
gitopssets-controller:
+ enabled: true
+ controllerManager:
+ manager:
+ args:
+ - --health-probe-bind-address=:8081
+ - --metrics-bind-address=127.0.0.1:8080
+ - --leader-elect
+ # enable the cluster generator which is not enabled by default
+ - --enabled-generators=GitRepository,Cluster,PullRequests,List,APIClient,Matrix,Config
+Gitopssets Controller Releases ENTERPRISE¶
v0.16.1¶
2023-09-06
v0.16.0¶
2023-09-05
v0.15.3¶
2023-08-17
v0.15.2¶
2023-08-17
v0.15.1¶
2023-08-17
v0.15.0¶
2023-08-10
v0.14.1¶
2023-07-26
v0.14.0¶
2023-07-14
v0.13.3¶
2023-06-26
v0.13.1¶
2023-06-21
v0.13.0¶
2023-06-20
v0.12.0¶
2023-05-24
v0.11.0¶
2023-05-10
v0.10.0¶
2023-04-28
v0.9.0¶
2023-04-27
v0.8.0¶
2023-04-13
v0.7.0¶
2023-03-30
v0.6.1¶
2023-03-20
GitOpsSets ENTERPRISE¶
Warning
This feature is in alpha and certain aspects will change
We're very excited for people to use this feature. However, please note that some changes will be made to the API and behavior, particularly to enhance security by implementing impersonation for more fine-grained control over how the generated resources are applied.
Introduction¶
GitOpsSets enable Platform Operators to have a single definition for an application for multiple environments and a fleet of clusters. A single definition can be used to generate the environment and cluster-specific configuration.
As an example, we can take an application that needs to be deployed to various environments (Dev, Test, Prod) built by a fleet of clusters. Each of those environments + clusters requires a specialized configuration powering the same Application. With GitOpsSets and the generators you just declare the template you want to use, the selector that will match the cluster of the inventory, and where to get the special configuration.
GitOpsSets will create out of the single resource all the objects and Flux primitives that are required to successfully deploy this application. An operation that required the editing of hundreds of files can now be done with a single command.
The initial generators that are coming with the preview release are:
Use Cases¶
Templating from Generators¶
Basics¶
Currently rendering templates operates in two phases:
Please read the security information below before using this.
General behaviour¶
GitOpsSets can be suspended, by setting the spec.suspend flag to be true.
When this is the case, updates will not be applied, no resources created or deleted.
In addition, a manual reconciliation can be requested by annotating a GitOpsSet with the reconcile.fluxcd.io/requestedAt annotation.
Generation¶
The simplest generator is the List generator.
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: gitopsset-sample
+spec:
+ generators:
+ - list:
+ elements:
+ - env: dev
+ team: dev-team
+ - env: production
+ team: ops-team
+ - env: staging
+ team: ops-team
+The elements in there are a set JSON of objects[^yaml], there are three in this example, and each of them has two keys, env and team.
Other generators provide different sets of keys and values.
The generators documentation below provides more information on what the other generators output.
Rendering templates¶
Templates are Kubernetes resources in YAML format.
Each template is rendered for each element generated by the generators.
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: gitopsset-sample
+spec:
+ generators:
+ - list:
+ elements:
+ - env: dev
+ team: dev-team
+ - env: production
+ team: ops-team
+ - env: staging
+ team: ops-team
+ templates:
+ - content:
+ kind: Kustomization
+ apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+ metadata:
+ name: "{{ .Element.env }}-demo"
+ labels:
+ app.kubernetes.io/name: go-demo
+ app.kubernetes.io/instance: "{{ .Element.env }}"
+ com.example/team: "{{ .Element.team }}"
+ spec:
+ interval: 5m
+ path: "./examples/kustomize/environments/{{ .Element.env }}"
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: go-demo-repo
+The generated elements are provided to the template in the Element scope, so .Element.dev refers to the dev field from the List element.
The output from all generators is exposed in the Element scope, not just List generators.
In addition to the .Element field, a .ElementIndex is also available, this represents the zero-based index into the set of generated elements.
NOTE: It's not recommended that you use this to name resources where the ordering of the queries for generating the elements is not guaranteed to be ordered, otherwise you could generate churn in resources as we look for resources by name when updating them, so, .ElementIndex 1 may not be the same as .ElementIndex 1 was the previous time, and this could cause resources to be updated unnecessarily with undesirable effects.
Repeating templates¶
The output from a generator is an array of JSON objects[^yaml], the keys of which can contain repeating elements, either further JSON objects, or scalar values.
It can be desirable to repeat a template for a repeated element in a generated value.
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: repeated-gitopsset-sample
+spec:
+ generators:
+ - list:
+ elements:
+ - env: dev
+ team: dev-team
+ teams:
+ - name: "team1"
+ - name: "team2"
+ - name: "team3"
+ - env: staging
+ team: staging-team
+ teams:
+ - name: "team4"
+ - name: "team5"
+ - name: "team6"
+ templates:
+ - repeat: "{ .teams }"
+ content:
+ kind: ConfigMap
+ apiVersion: v1
+ metadata:
+ name: "{{ .Repeat.name }}-demo"
+ data:
+ name: "{{ .Repeat.name }}-demo"
+ team: "{{ .Element.team }}"
+The template repeat field is a JSONPath expression that is applied to each element during the template rendering.
Templates that use repeat will have two separate scopes for the template params, .Element which is the top-level element generated by the generator, and the additional .Repeat scope, which is the repeating element.
In this case, six different ConfigMaps are generated, three for the "dev-team" and three for the "staging-team".
As with the .ElementIndex, for repeated elements both .ElementIndex and .RepeatIndex are available.
Delimiters¶
The default delimiters for the template engine are {{ and }}, which is the same as the Go template engine.
These can be changed by adding an annotation to the GitOpsSet:
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: gitopsset-sample
+ annotations:
+ templates.weave.works/delimiters: "${{,}}"
+Changing the delimiters can useful for:
Unquoted values¶
In yaml {{ is invalid syntax and needs to be quoted. If you need to provide a un-quoted number value like replicas: 3 you should use the ${{,}} delimiters.
Unquoted values allow you to include objects in your templates too.
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: gitopsset-sample
+ annotations:
+ templates.weave.works/delimiters: "${{,}}"
+spec:
+ generators:
+ - list:
+ elements:
+ - env: dev
+ resources:
+ limits:
+ cpu: 100m
+ memory: 128Mi
+ - env: staging
+ resources:
+ limits:
+ cpu: 100m
+ memory: 128Mi
+ templates:
+ - content:
+ kind: Deployment
+ apiVersion: apps/v1
+ metadata:
+ name: go-demo
+ spec:
+ template:
+ spec:
+ containers:
+ - name: go-demo
+ image: weaveworks/go-demo:0.2.0
+ resources: ${{ .Element.resources | toJson }}
+With the default {{,}} delimiters this would fail as the "resources" field would need to be quoted.
Again, if we quote them we would get a string value, not an object.
Generators¶
We currently provide these generators: - list - pullRequests - gitRepository - ociRepository - matrix - apiClient - cluster - imagepolicy - config
List generator¶
This is the simplest generator, which is a hard-coded array of JSON objects, described as YAML mappings.
GitRepository generator¶
The GitRepository generator operates on Flux GitRepositories.
When a GitRepository is updated, this will trigger a regeneration of templates.
The generator operates in two different ways, you can parse files (YAML or JSON) into Elements, or you can scan directories for subdirectories.
Generation from files¶
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: repository-sample
+spec:
+ generators:
+ - gitRepository:
+ repositoryRef: go-demo-repo
+ files:
+ - path: examples/generation/dev.yaml
+ - path: examples/generation/production.yaml
+ - path: examples/generation/staging.yaml
+ templates:
+ - content:
+ kind: Kustomization
+ apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+ metadata:
+ name: "{{ .Element.env }}-demo"
+ labels:
+ app.kubernetes.io/name: go-demo
+ app.kubernetes.io/instance: "{{ .Element.env }}"
+ com.example/team: "{{ .Element.team }}"
+ spec:
+ interval: 5m
+ path: "./examples/kustomize/environments/{{ .Element.env }}"
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: go-demo-repo
+In this example, a Flux GitRepository called go-demo-repo in the same namespace as the GitOpsSet will be tracked, and Kustomization resources will be generated from the three files listed.
These files can be JSON or YAML.
In this example we expect to find the following structure in the files:
env: dev
+team: developers
+Changes pushed to the GitRepository will result in rereconciliation of the templates into the cluster.
For security reasons, you need to explicitly list out the files that the generator should parse.
Generation from directories¶
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ labels:
+ app.kubernetes.io/name: gitopsset
+ app.kubernetes.io/instance: gitopsset-sample
+ app.kubernetes.io/part-of: gitopssets-controller
+ app.kubernetes.io/managed-by: kustomize
+ app.kubernetes.io/created-by: gitopssets-controller
+ name: repository-sample
+spec:
+ generators:
+ - gitRepository:
+ repositoryRef: go-demo-repo
+ directories:
+ - path: examples/kustomize/environments/*
+ templates:
+ - content:
+ kind: Kustomization
+ apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+ metadata:
+ name: "{{ .Element.Base }}-demo"
+ labels:
+ app.kubernetes.io/name: go-demo
+ app.kubernetes.io/instance: "{{ .Element.Base }}"
+ com.example/team: "{{ .Element.Base }}"
+ spec:
+ interval: 5m
+ path: "{{ .Element.Directory }}"
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: go-demo-repo
+In this example, a Flux GitRepository called go-demo-repo in the same namespace as the GitOpsSet will be tracked, and Kustomization resources are generated from paths within the examples/kustomize/environments/* directory within the repository.
Each generated element has two keys, .Element.Directory which will be a repo-relative path and .Element.Base which contains the last element of the path, for example, for a directory ./examples/kustomize/environments/production this will be production.
It is also possible to exclude paths from the generated list, for example, if you do not want to generate for a directory you can exclude it with:
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: repository-sample
+spec:
+ generators:
+ - gitRepository:
+ repositoryRef: go-demo-repo
+ directories:
+ - path: examples/kustomize/environments/*
+ - path: examples/kustomize/environments/production
+ exclude: true
+ templates:
+ - content:
+In this case, all directories that are subdirectories of examples/kustomize/environments will be generated, but not examples/kustomize/environments/production.
Note: The directory tree detection is restricted to the same directory as the path, no recursion is done.
In fact the path is treated as a Glob.
OCIRepository generator¶
The OCIRepository generator operates on Flux OCIRepositories.
When an OCIRepository is updated, this will trigger a regeneration of templates.
The OCIRepository generator operates in exactly the same way as the GitRepository generator, except it operates on OCIRepositories.
Generation from files¶
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: oci-repository-sample
+spec:
+ generators:
+ - ociRepository:
+ repositoryRef: go-demo-oci-repo
+ files:
+ - path: examples/generation/dev.yaml
+ - path: examples/generation/production.yaml
+ - path: examples/generation/staging.yaml
+ templates:
+ - content:
+ kind: Kustomization
+ apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+ metadata:
+ name: "{{ .Element.env }}-demo"
+ labels:
+ app.kubernetes.io/name: go-demo
+ app.kubernetes.io/instance: "{{ .Element.env }}"
+ com.example/team: "{{ .Element.team }}"
+ spec:
+ interval: 5m
+ path: "./examples/kustomize/environments/{{ .Element.env }}"
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: go-demo-repo
+PullRequests generator¶
This will require to make authenticated requests to your Git hosting provider e.g. GitHub, GitLab, Bitbucket etc.
It does only require read-only access, but all API tokens should be guarded as carefully as possible, what is a "read-only" token today, might become a token with higher-privilege in the future.
There have been many security compromises using API access tokens, do not let this happen to you!
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: pull-requests-sample
+spec:
+ generators:
+ - pullRequests:
+ interval: 5m
+ driver: github
+ repo: bigkevmcd/go-demo
+ secretRef:
+ name: github-secret
+ templates:
+ - content:
+ apiVersion: source.toolkit.fluxcd.io/v1beta2
+ kind: GitRepository
+ metadata:
+ name: "pr-{{ .Element.Number }}-gitrepository"
+ namespace: default
+ spec:
+ interval: 5m0s
+ url: "{{ .Element.CloneURL }}"
+ ref:
+ branch: "{{ .Element.Branch }}"
+ - content:
+ apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+ kind: Kustomization
+ metadata:
+ name: "pr-{{ .Element.Number }}-demo"
+ namespace: default
+ spec:
+ interval: 5m
+ path: "./examples/kustomize/environments/dev"
+ prune: true
+ targetNamespace: "{{ .Element.Branch }}-ns"
+ sourceRef:
+ kind: GitRepository
+ name: "pr-{{ .Element.Number }}-gitrepository"
+This example will poll "github.com/bigkevmcd/go-demo" for open pull requests and trigger the deployment of these by creating a Flux GitRepository and a Kustomization to deploy.
As the generator only queries open pull requests, when a PR is closed, the generated resources will be removed.
For non-public installations, you can configure the serverURL field and point it to your own installation.
The driver field can be github or gitlab or bitbucketserver, other options can be supported from go-scm.
The forks flag field can be used to indicate whether to include forks in the target pull requests or not. If set to true any pull request from a fork repository will be included, otherwise if false or not indicated the pull requests from fork repositories are discarded.
Additionally labels can be provided for querying pull requests with matching labels e.g.
- pullRequests:
+ interval: 5m
+ driver: github
+ repo: bigkevmcd/go-demo
+ secretRef:
+ name: github-secret
+ forks: false
+ labels:
+ - deploy
+The fields emitted by the pull-request are as follows:
Create a read-only token that can list Pull Requests, and store it in a secret:
$ kubectl create secret generic github-secret \
+ --from-literal password=<insert access token here>
+Matrix generator¶
The matrix generator doesn't generate resources by itself. It combines the results of generation from other generators e.g.:
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: matrix-sample
+spec:
+ generators:
+ - matrix:
+ generators:
+ - gitRepository:
+ repositoryRef: go-demo-repo
+ files:
+ - path: examples/generation/dev.yaml
+ - path: examples/generation/production.yaml
+ - path: examples/generation/staging.yaml
+ - list:
+ elements:
+ - cluster: dev-cluster
+ version: 1.0.0
+Given the files mentioned all have the following structure:
env: dev
+team: developers
+This will result in three sets of generated parameters, which are a combination of the maps in the files in the gitRepository, and the elements in the list generator, this can result in a combinatorial explosion of resources being created in your cluster.
- env: dev
+ team: developers
+ cluster: dev-cluster
+ version: 1.0.0
+- env: staging
+ team: staging-team
+ cluster: dev-cluster
+ version: 1.0.0
+- env: production
+ team: production-team
+ cluster: dev-cluster
+ version: 1.0.0
+These can be referenced in the templates, note that all keys in the merged generators from the Matrix are contained in the Element scope.
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: matrix-sample
+spec:
+ generators:
+ - matrix:
+ generators:
+ - gitRepository:
+ repositoryRef: go-demo-repo
+ files:
+ - path: examples/generation/dev.yaml
+ - path: examples/generation/production.yaml
+ - path: examples/generation/staging.yaml
+ - list:
+ elements:
+ - cluster: dev-cluster
+ version: 1.0.0
+ templates:
+ - content:
+ kind: Kustomization
+ apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+ metadata:
+ name: "{{ .Element.env }}-demo"
+ labels:
+ app.kubernetes.io/name: go-demo
+ app.kubernetes.io/instance: "{{ .Element.env }}"
+ com.example/team: "{{ .Element.team }}"
+ com.example/cluster: "{{ .Element.cluster }}"
+ com.example/version: "{{ .Element.version }}"
+ spec:
+ interval: 5m
+ path: "./examples/kustomize/environments/{{ .Element.env }}"
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: go-demo-repo
+Optional Name for Matrix elements¶
If you want to use two generators in a Matrix that output the same fields, they will collide, for example, the ImagePolicy generator outputs a latestImage field, if you have two, they will collide.
You can provide a name for the generator in the Matrix:
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: matrix-sample
+spec:
+ generators:
+ - matrix:
+ generators:
+ - name: gen1
+ gitRepository:
+ repositoryRef: go-demo-repo
+ files:
+ - path: examples/generation/dev.yaml
+ - path: examples/generation/production.yaml
+ - path: examples/generation/staging.yaml
+ - name: gen2
+ list:
+ elements:
+ - cluster: dev-cluster
+ version: 1.0.0
+ templates:
+ - content:
+ kind: Kustomization
+ apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+ metadata:
+ name: "{{ .Element.gen1.env }}-demo"
+ labels:
+ app.kubernetes.io/name: go-demo
+ app.kubernetes.io/instance: "{{ .Element.gen1.env }}"
+ com.example/team: "{{ .Element.gen1.team }}"
+ com.example/cluster: "{{ .Element.gen2.cluster }}"
+ com.example/version: "{{ .Element.gen2.version }}"
+ spec:
+ interval: 5m
+ path: "./examples/kustomize/environments/{{ .Element.gen1.env }}"
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: go-demo-repo
+The example above will yield:
- gen1:
+ env: dev
+ team: developers
+ gen2:
+ cluster: dev-cluster
+ ersion: 1.0.0
+- gen1:
+ env: staging
+ team: staging-team
+ gen2:
+ cluster: dev-cluster
+ version: 1.0.0
+- gen1:
+ env: production
+ team: production-team
+ gen2:
+ cluster: dev-cluster
+ version: 1.0.0
+Single Element for Matrix¶
A matrix generator will normally generate a cartesian result, but you can also generate a single result.
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: single-element-matrix-sample
+spec:
+ generators:
+ - matrix:
+ singleElement: true
+ generators:
+ - name: staging
+ cluster:
+ selector:
+ matchLabels:
+ env: staging
+ - name: production
+ cluster:
+ selector:
+ matchLabels:
+ env: production
+This would query for clusters matching the respective labels.
The resulting output would look like this (in YAML):
- production:
+ - ClusterAnnotations: {}
+ ClusterLabels:
+ env: production
+ ClusterName: production-cluster1
+ ClusterNamespace: clusters
+ - ClusterAnnotations: {}
+ ClusterLabels:
+ env: production
+ ClusterName: production-cluster2
+ ClusterNamespace: clusters
+ staging:
+ - ClusterAnnotations: {}
+ ClusterLabels:
+ env: staging
+ ClusterName: staging-cluster1
+ ClusterNamespace: clusters
+ - ClusterAnnotations: {}
+ ClusterLabels:
+ env: staging
+ ClusterName: staging-cluster2
+ ClusterNamespace: clusters
+Compare this with the alternative without the singleElement flag:
- production:
+ ClusterAnnotations: {}
+ ClusterLabels:
+ env: production
+ ClusterName: production-cluster1
+ ClusterNamespace: clusters
+ staging:
+ ClusterAnnotations: {}
+ ClusterLabels:
+ env: staging
+ ClusterName: staging-cluster1
+ ClusterNamespace: clusters
+- production:
+ ClusterAnnotations: {}
+ ClusterLabels:
+ env: production
+ ClusterName: production-cluster2
+ ClusterNamespace: clusters
+ staging:
+ ClusterAnnotations: {}
+ ClusterLabels:
+ env: staging
+ ClusterName: staging-cluster1
+ ClusterNamespace: clusters
+- production:
+ ClusterAnnotations: {}
+ ClusterLabels:
+ env: production
+ ClusterName: production-cluster1
+ ClusterNamespace: clusters
+ staging:
+ ClusterAnnotations: {}
+ ClusterLabels:
+ env: staging
+ ClusterName: staging-cluster2
+ ClusterNamespace: clusters
+- production:
+ ClusterAnnotations: {}
+ ClusterLabels:
+ env: production
+ ClusterName: production-cluster2
+ ClusterNamespace: clusters
+ staging:
+ ClusterAnnotations: # omitted
+ ClusterLabels:
+ env: staging
+ ClusterName: staging-cluster2
+ ClusterNamespace: clusters
+In the singleElement case, there is only one generated element, only one template will be rendered for each content item.
If the Matrix generators are unnamed, they will be grouped under a top-level .Matrix name.
apiClient generator¶
This generator is configured to poll an HTTP endpoint and parse the result as the generated values.
This will poll an endpoint on the interval, instead of using the simpler to use PullRequest generator, you can access GitHub's API with the APIClient generator.
The PullRequest generator is simpler to use, and works across multiple different git-providers.
The GitHub documentation for the API endpoint shows:
curl \
+ -H "Accept: application/vnd.github+json" \
+ -H "Authorization: Bearer <YOUR-TOKEN>"\
+ -H "X-GitHub-Api-Version: 2022-11-28" \
+ https://api.github.com/repos/OWNER/REPO/pulls
+This can be translated into...
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ labels:
+ app.kubernetes.io/name: gitopsset
+ app.kubernetes.io/instance: gitopsset-sample
+ app.kubernetes.io/part-of: gitopssets-controller
+ app.kubernetes.io/managed-by: kustomize
+ app.kubernetes.io/created-by: gitopssets-controller
+ name: api-client-sample
+spec:
+ generators:
+ - apiClient:
+ interval: 5m
+ endpoint: https://api.github.com/repos/bigkevmcd/go-demo/pulls
+ headersRef:
+ name: github-secret
+ kind: Secret
+ templates:
+ - content:
+ apiVersion: source.toolkit.fluxcd.io/v1beta2
+ kind: GitRepository
+ metadata:
+ name: "pr-{{ .Element.id | toJson}}-gitrepository"
+ namespace: default
+ spec:
+ interval: 5m0s
+ url: "{{ .Element.head.repo.clone_url }}"
+ ref:
+ branch: "{{ .Element.head.ref }}"
+ - content:
+ apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+ kind: Kustomization
+ metadata:
+ name: "pr-{{ .Element.id | toJson }}-demo"
+ namespace: default
+ spec:
+ interval: 5m
+ path: "./examples/kustomize/environments/dev"
+ prune: true
+ targetNamespace: "{{ .Element.head.ref }}-ns"
+ sourceRef:
+ kind: GitRepository
+ name: "pr-{{ .Element.id | toJson }}-gitrepository"
+As with the Pull Request generator, this also requires a secret token to be able to access the API
We need to pass this as an HTTP header.
apiVersion: v1
+kind: Secret
+metadata:
+ name: github-secret
+ namespace: default
+type: Opaque
+stringData:
+ Accept: application/vnd.github+json
+ Authorization: Bearer ghp_<redacted>
+ X-GitHub-Api-Version: "2022-11-28"
+The keys in the secret match the command-line example using curl.
Unlike the Pull Request generator, you need to figure out the paths to the elements yourself.
APIClient JSONPath¶
Not all APIs return an array of JSON objects, sometimes it's nested within a result type structure e.g.
{
+ "things": [
+ {
+ "env": "dev",
+ "team": "dev-team"
+ },
+ {
+ "env": "production",
+ "team": "opts-team"
+ },
+ {
+ "env": "staging",
+ "team": "opts-team"
+ }
+ ]
+}
+You can use JSONPath to extract the fields from this data...
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ labels:
+ app.kubernetes.io/name: gitopsset
+ app.kubernetes.io/instance: gitopsset-sample
+ app.kubernetes.io/part-of: gitopssets-controller
+ app.kubernetes.io/managed-by: kustomize
+ app.kubernetes.io/created-by: gitopssets-controller
+ name: api-client-sample
+spec:
+ generators:
+ - apiClient:
+ interval: 5m
+ endpoint: https://api.example.com/demo
+ jsonPath: "{ $.things }"
+This will generate three maps for templates, with just the env and team keys.
APIClient POST body¶
Another piece of functionality in the APIClient generator is the ability to POST JSON to the API.
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ labels:
+ app.kubernetes.io/name: gitopsset
+ app.kubernetes.io/instance: gitopsset-sample
+ app.kubernetes.io/part-of: gitopssets-controller
+ app.kubernetes.io/managed-by: kustomize
+ app.kubernetes.io/created-by: gitopssets-controller
+ name: api-client-sample
+spec:
+ generators:
+ - apiClient:
+ interval: 5m
+ endpoint: https://api.example.com/demo
+ body:
+ name: "testing"
+ value: "testing2"
+This will send a request body as JSON (Content-Type "application/json") to the server and interpret the result.
The JSON body sent will look like this:
{ "name": "testing", "value": "testing2" }
+APIClient simple results¶
Instead of using the JSONPath to extract from a complex structure, you can configure the result to be a single element.
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ labels:
+ app.kubernetes.io/name: gitopsset
+ app.kubernetes.io/instance: gitopsset-sample
+ app.kubernetes.io/part-of: gitopssets-controller
+ app.kubernetes.io/created-by: gitopssets-controller
+ name: api-client-sample
+spec:
+ generators:
+ - apiClient:
+ singleElement: true
+ interval: 5m
+ endpoint: https://api.example.com/demo
+Whatever result is parsed from the API endpoint will be returned as a map in a single element.
For generation, you might need to use the repeat mechanism to generate repeating results.
APIClient Custom CA¶
If the API endpoint you are accessing requires a custom CA you can provide this via the secret field.
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ labels:
+ app.kubernetes.io/name: gitopsset
+ app.kubernetes.io/instance: gitopsset-sample
+ app.kubernetes.io/part-of: gitopssets-controller
+ app.kubernetes.io/created-by: gitopssets-controller
+ name: api-client-sample
+spec:
+ generators:
+ - apiClient:
+ singleElement: true
+ interval: 5m
+ endpoint: https://api.example.com/demo
+ secretRef:
+ name: https-ca-credentials
+This secret should look like this:
---
+apiVersion: v1
+kind: Secret
+metadata:
+ name: https-ca-credentials
+type: Opaque
+data:
+ caFile: <BASE64>
+The request will be made with the custom CA.
Cluster generator¶
The cluster generator generates from in-cluster GitOpsCluster resources.
For example, this GitOpsSet will generate a Kustomization resource for each cluster matching the Label selector.
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: cluster-sample
+spec:
+ generators:
+ - cluster:
+ selector:
+ matchLabels:
+ env: dev
+ team: dev-team
+ templates:
+ - content:
+ kind: Kustomization
+ apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+ metadata:
+ name: "{{ .Element.ClusterName }}-demo"
+ labels:
+ app.kubernetes.io/name: go-demo
+ app.kubernetes.io/instance: "{{ .Element.ClusterName }}"
+ com.example/team: "{{ .Element.ClusterLabels.team }}"
+ spec:
+ interval: 5m
+ path: "./examples/kustomize/environments/{{ .Element.ClusterLabels.env }}"
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: go-demo-repo
+The following fields are generated for each GitOpsCluster.
If the selector is not provided, all clusters from all namespaces will be returned:
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: cluster-sample
+spec:
+ generators:
+ - cluster: {}
+Otherwise if the selector is empty, no clusters will be generated:
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: cluster-sample
+spec:
+ generators:
+ - cluster:
+ selector: {}
+ImagePolicy generator¶
The ImagePolicy generator works with the Flux Image Automation.
When an ImagePolicy is updated, this will trigger a regeneration of templates.
The generated elements have the following fields:
This can be used simply, to create a deployment with an image...or, combined with a Matrix generator, to manage multiple workloads with the same image.
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: imagepolicy-example
+ namespace: default
+spec:
+ generators:
+ - imagePolicy:
+ policyRef: podinfo
+ templates:
+ - content:
+ kind: ConfigMap
+ apiVersion: v1
+ metadata:
+ name: "demo-configmap"
+ data:
+ image: "{{ .Element.latestImage }}"
+In this example, a ConfigMap is generated containing the latest image whenever an ImagePolicy called podinfo is updated.
Combined in a Matrix, like this, it will generate two ConfigMaps with the values.
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: imagepolicy-matrix-example
+ namespace: default
+spec:
+ generators:
+ - matrix:
+ generators:
+ - imagePolicy:
+ policyRef: podinfo
+ - list:
+ elements:
+ - cluster: dev-cluster
+ version: 1.0.0
+ - cluster: prod-cluster
+ version: 1.0.0
+ templates:
+ - content:
+ kind: ConfigMap
+ apiVersion: v1
+ metadata:
+ name: "demo-configmap-{{ .Element.cluster }}"
+ data:
+ image: "{{ .Element.latestImage }}"
+ cluster: "{{ .Element.cluster }}"
+ version: "{{ .Element.version }}"
+The resulting ConfigMaps look like this:
$ kubectl get configmaps
+NAME DATA AGE
+demo-configmap-dev-cluster 3 3m19s
+demo-configmap-prod-cluster 3 3m19s
+With the templated fields like this:
apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: demo-configmap-dev-cluster
+ namespace: default
+data:
+ cluster: dev-cluster
+ image: stefanprodan/podinfo:5.1.4
+ version: 1.0.0
+apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: demo-configmap-prod-cluster
+ namespace: default
+data:
+ cluster: prod-cluster
+ image: stefanprodan/podinfo:5.1.4
+ version: 1.0.0
+Config generator¶
The Config generator with Kubernetes ConfigMaps and Secrets.
When an ConfigMap or Secret is updated, this will trigger a regeneration of templates.
This can be used simply, to create a resource with an config variable...or, combined with a Matrix generator, to manage multiple workloads with the same values.
With the existing ConfigMap
apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: test-cm
+data:
+ name: test-config
+ demo: test-value
+apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: config-sample
+spec:
+ generators:
+ - config:
+ kind: ConfigMap
+ name: test-cm
+ templates:
+ - content:
+ kind: ConfigMap
+ apiVersion: v1
+ metadata:
+ name: "{{ .Element.name }}-demo"
+ labels:
+ app.kubernetes.io/name: go-demo
+ app.kubernetes.io/instance: "{{ .Element.name }}"
+ data:
+ generatedValue: "{{ .Element.demo }}"
+ConfigMap is generated containing the value of the "demo" field from the existing ConfigMap test-cm. As with the other generators, the Config generator can be combined with other generators:
This will generate two ConfigMaps with the values.
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: imagepolicy-matrix-example
+ namespace: default
+spec:
+ generators:
+ - matrix:
+ generators:
+ - config:
+ kind: ConfigMap
+ name: test-cm
+ - list:
+ elements:
+ - cluster: dev-cluster
+ version: 1.0.0
+ - cluster: prod-cluster
+ version: 1.0.0
+ templates:
+ - content:
+ kind: ConfigMap
+ apiVersion: v1
+ metadata:
+ name: "demo-configmap-{{ .Element.cluster }}"
+ data:
+ generatedValue: "{{ .Element.demo }}"
+ cluster: "{{ .Element.cluster }}"
+ version: "{{ .Element.version }}"
+The resulting ConfigMaps look like this:
$ kubectl get configmaps
+NAME DATA AGE
+demo-configmap-dev-cluster 3 3m19s
+demo-configmap-prod-cluster 3 3m19s
+With the templated fields like this:
apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: demo-configmap-dev-cluster
+ namespace: default
+data:
+ cluster: dev-cluster
+ generatedValue: test-value
+ version: 1.0.0
+apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: demo-configmap-prod-cluster
+ namespace: default
+data:
+ cluster: prod-cluster
+ generatedValue: test-value
+ version: 1.0.0
+Templating functions¶
Currently, the Sprig functions are available in the templating, with some functions removed[^sprig] for security reasons.
In addition, we also provide two additional functions:
The examples below assume an element that looks like this:
{
+ "team": "engineering dev"
+}
+sanitize template function¶
And a template that looks like this:
kind: Service
+metadata:
+ name: {{ sanitize .Element.team }}-demo
+This would output:
kind: Service
+metadata:
+ name: engineeringdev-demo
+getordefault¶
For template that looks like this:
kind: Service
+metadata:
+ name: {{ getordefault .Element "name" "defaulted" }}-demo
+This would output:
kind: Service
+metadata:
+ name: defaulted-demo
+If the key to get does exist in the .Element it will be inserted, the "default" is only inserted if it doesn't exist.
Security¶
Warning
Generating resources and applying them directly into your cluster can be dangerous to the health of your cluster.
This is especially true for the GitRepository generator, where it may not be obvious to the author of the files, or the author of the template the consequences of the template rendering.
The default ServiceAccount that is used by the gitopssets-controller is extremely limited, and can not create resources, you will need to explicitly grant permissions to create any of the resources you declare in the template, missing permissions will appear in the controller logs.
It is not recommended that you create a role with blanket permissions, under the right circumstances, someone could accidentally or maliciously overwrite the cluster control-plane, which could be very dangerous.
Limiting via service-accounts¶
You can configure the service-account that is used to create resources.
apiVersion: templates.weave.works/v1alpha1
+kind: GitOpsSet
+metadata:
+ name: matrix-sample
+spec:
+ # the controller will impersonate this service account
+ serviceAccountName: test-sa
+ generators:
+ - list:
+ elements:
+ - env: dev
+ team: dev-team
+ - env: production
+ team: ops-team
+ - env: staging
+ team: ops-team
+ templates:
+ - content:
+ kind: Kustomization
+ apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+ metadata:
+ name: "{{ .Element.env }}-demo"
+ labels:
+ app.kubernetes.io/name: go-demo
+ app.kubernetes.io/instance: "{{ .Element.env }}"
+ com.example/team: "{{ .Element.team }}"
+ spec:
+ interval: 5m
+ path: "./examples/kustomize/environments/{{ .Element.env }}"
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: go-demo-repo
+gitopsset-controller configuration¶
The enabled generators can be configured via the --enabled-generators flag, which takes a comma separated list of generators to enable.
The default is to enable all generators.
For example to enable only the List and GitRepository generators:
--enabled-generators=List,GitRepository
+When a GitOpsSet that uses disabled generators is created, the disabled generators will be silently ignored.
Kubernetes Process Limits¶
GitOpsSets can be memory-hungry, for example, the Matrix generator will generate a cartesian result with multiple copies of data.
The OCI and GitRepository generators will extract tarballs, the API Generator queries upstream APIs and parses the JSON, and the Config generators will load Secret and ConfigMap resources, all these can lead to using significant amounts of memory.
Extracting tarballs can also prove to be CPU intensive, especially where there are lots of files, and you have a very frequent regeneration period.
To this end, you will need to monitor the controller metrics, and maybe increase the limits available to the controller.
For example, to increase the amount of memory available to the controller:
resources:
+ limits:
+ cpu: 1000m
+ memory: 2Gi
+ requests:
+ cpu: 100m
+ memory: 64Mi
+Notifications¶
Events are enabled which will trigger Kubernetes events when successful reconciliation occurs with a Normal event or when reconciliation fails with an Error event. Fluxcd's Events package is used including the EventRecorder to record these events.
To configure receiving the recorded events on a specific host, this can be provided via the --events-addr flag in RUN_ARGS when starting the controller. This can be any HTTP endpoint.
See fluxcd event for the struct of the event created.
[^yaml]: These are written as YAML mappings [^sprig]: The following functions are removed "env", "expandenv", "getHostByName", "genPrivateKey", "derivePassword", "sha256sum", "base", "dir", "ext", "clean", "isAbs", "osBase", "osDir", "osExt", "osClean", "osIsAbs"
Anonymous Access
Important
Alone, this is an insecure method of securing your dashboard.
It is designed to be used with other external authentication systems like auth proxies.
Configuring Anonymous access¶
Set the following values in the Helm Chart:
#
+additionalArgs:
+- --insecure-no-authentication-user=gitops-test-user
+#
+The value of the --insecure-no-authentication-user flag is the kubernetes User to be impersonated to make requests into the cluster.
When this flag is set all other authentication methods (e.g. those specified via --auth-methods) are disabled.
No login screen will be displayed when accessing the dashboard.
Example ClusterRole¶
You can bind the user provided to a ClusterRole with a ClusterRoleBinding.
---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+ name: minimum-weavegitops-role
+rules:
+- apiGroups: [""]
+ resources: ["secrets","pods","events"]
+ verbs: ["get","list"]
+- apiGroups: ["apps"]
+ resources: ["deployments", "replicasets"]
+ verbs: ["get","list"]
+- apiGroups: ["kustomize.toolkit.fluxcd.io"]
+ resources: ["kustomizations"]
+ verbs: ["get","list"]
+- apiGroups: ["helm.toolkit.fluxcd.io"]
+ resources: ["helmreleases"]
+ verbs: ["get","list"]
+- apiGroups: ["source.toolkit.fluxcd.io"]
+ resources: ["*"]
+ verbs: ["get","list"]
+- apiGroups: [""]
+ resources: ["events"]
+ verbs: ["get","list","watch"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+ name: gitops-test-user-binding
+roleRef:
+ apiGroup: rbac.authorization.k8s.io
+ kind: ClusterRole
+ name: minimum-weavegitops-role
+subjects:
+ - kind: User
+ name: gitops-test-user
+This would allow access to any resource.
Displaying Custom Metadata¶
Weave GitOps lets you add annotations with custom metadata to your Flux automations and sources, and they will be displayed in the main UI.
For example, you might use this to add links to dashboards, issue systems, or documentation and comments that you wish to be directly visible in the GitOps UI.
We will use the podinfo application that we installed in the getting started guide as an example. Open up the podinfo kustomization and add annotations to it so it looks like this:
./clusters/my-cluster/podinfo-kustomization.yaml
---
+apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+kind: Kustomization
+metadata:
+ name: podinfo
+ namespace: flux-system
+// highlight-start
+ annotations:
+ metadata.weave.works/description: |
+ Podinfo is a tiny web application made with Go that showcases best practices of running microservices in Kubernetes.
+ Podinfo is used by CNCF projects like Flux and Flagger for end-to-end testing and workshops.
+ metadata.weave.works/grafana-dashboard: https://grafana.my-org.example.com/d/podinfo-dashboard
+// highlight-end
+spec:
+ interval: 5m0s
+ path: ./kustomize
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: podinfo
+ targetNamespace: flux-system
+Close the file and commit and push your changes.
Back in your GitOps dashboard, navigate to the 'Applications' tab and select the podinfo kustomization. At the bottom of the 'Details' section you will see the new 'Metadata' entries:
Restrictions
Upgrade to Flux GA¶
We are very excited for the release of the Flux v2.0 GA!
This guide aims to answer some common questions before starting the upgrade, and provides step-by-step instructions.
Before Starting the Upgrade¶
Useful terms used in this guide:
FAQ¶
Here you can find the most common questions around upgrading.
Why Upgrade to Flux GA¶
Although Flux Beta APIs have been stable and used in production for quite some time, Flux GA is the main supported API version for new features and development. Features like horizontal scaling are only available in Flux GA. Also, beta APIs will be removed after six months.
Can I Use Weave GitOps with Flux GA?¶
Yes. This has been possible since Weave Gitops v0.22.0. Use the latest available release for the best experience.
Can I Use Weave GitOps Enterprise with Flux GA?¶
Yes. This has been possible since Weave GitOps Enterprise v0.22.0. Use the latest available release for the best experience.
The following limitations are knowns by version:
v0.23.0 onwards¶
No limitations
v0.22.0¶
If you are using GitOpsSets, upgrade that component to v0.10.0 for Flux GA compatibility. Update the Weave GitOps Enterprise HelmRelease values to use the new version.
gitopssets-controller:
+ controllerManager:
+ manager:
+ image:
+ tag: v0.10.0
+Can I Use Weave GitOps with Flux v2 0.x (pre-GA versions)?¶
As of Weave GitOps v0.29, only Flux v2.0 GA is supported. Please follow the Upgrade section to help you with the process.
Earlier versions of Weave GitOps work with both Flux v2 GA and Flux v2 0.x (the pre-GA ones), but it is encouraged that you upgrade to the latest version for the best experience.
Upgrade¶
Hosted flux?
If you are using a hosted Flux version, please check with your provider if they support Flux GA before upgrading following this guide. Known hosted Flux providers:
As of writing they do not yet support the new version, so please wait before upgrading to Flux GA.
Below, we'll take you through the multiple steps required to migrate to your system to Flux GA. After each step the cluster will be in a working state, so you can take your time to complete the migration.
1. Upgrade to Flux GA on your existing leaf clusters and management clusters¶
Follow the upgrade instructions from the Flux v2.0.0 release notes.
At minimum, you'll need to rerun the flux bootstrap command on your leaf clusters and management clusters.
You'll also need to bump API versions in your manifests to v1 as described in the Flux upgrade instructions:
Bumping the APIs version in manifests can be done gradually. It is advised to not delay this procedure as the beta versions will be removed after 6 months.
At this stage all clusters are running Flux GA.
2. Upgrade to Flux GA in ClusterBootstrapConfigs¶
First, we ensure any new clusters are bootstrapped with Flux GA. Then we'll upgrade the existing clusters.
ClusterBootstrapConfig will most often contain an invocation of flux bootstrap. Make sure the image is using v2.
Expand to see example
diff --git a/tools/dev-resources/user-guide/cluster-bootstrap-config.yaml b/tools/dev-resources/user-guide/cluster-bootstrap-config.yaml
+index bd41ec036..1b21df860 100644
+--- a/tools/dev-resources/user-guide/cluster-bootstrap-config.yaml
++++ b/tools/dev-resources/user-guide/cluster-bootstrap-config.yaml
+@@ -1,34 +1,34 @@
+apiVersion: capi.weave.works/v1alpha1
+kind: ClusterBootstrapConfig
+metadata:
+name: capi-gitops
+namespace: default
+spec:
+clusterSelector:
+ matchLabels:
+ weave.works/capi: bootstrap
+jobTemplate:
+ generateName: "run-gitops-{{ .ObjectMeta.Name }}"
+ spec:
+ containers:
+- - image: ghcr.io/fluxcd/flux-cli:v0.34.0
++ - image: ghcr.io/fluxcd/flux-cli:v2.0.0
+ name: flux-bootstrap
+ ...
+At this stage, your new bootstrapped clusters will run Flux GA.
3. Upgrade to latest WGE¶
Use your regular WGE upgrade procedure to bring it to the latest version
At this stage you have Weave GitOps running Flux GA.
4. Upgrade GitOpsTemplates, GitOpsSets, and ClusterBootstrapConfigs¶
Bumping the APIs version in manifests can be done gradually. We advise against delaying this procedure as the Beta versions will be removed after six months.
GitOpsTemplate and CAPITemplate¶
Update GitRepository and Kustomization CRs in the spec.resourcetemplates to v1 as described in the flux upgrade instructions.
GitOpsSets¶
Update GitRepository and Kustomization CRs in the spec.template of your GitOpsSet resources to v1 as described in the Flux upgrade instructions.
5. Future steps¶
If you haven't done it yet, plan to update your Kustomization , GitRepository and Receiver resources to v1, you can also upgrade to the future release of Flux that will drop support for < v1 APIs.
Contact us¶
If you find any issues, please let us know via support.
Support
Community¶
👋 Come talk to us and other users in the #weave-gitops channel on Weaveworks Community Slack.
Invite yourself if you haven't joined yet.
Flux¶
The Flux project has a fantastic community to help support your GitOps journey, find more details on how to reach out via their community page
Commercial Support¶
Weaveworks provides Weave GitOps Enterprise, a continuous operations product that makes it easy to deploy and manage Kubernetes clusters and applications at scale in any environment. The single management console automates trusted application delivery and secure infrastructure operations on premise, in the cloud and at the edge.
To discuss your support needs, please contact us at sales@weave.works.
Recommended resources¶
Got a suggestion for this list? Please open a pull request using the "Edit this page" link at the bottom.
Weaveworks materials¶
Other¶
Welcome to MkDocs¶
For full documentation visit mkdocs.org and Material theme for mkdocs. Follow the installation instructions here https://squidfunk.github.io/mkdocs-material/getting-started/
Commands¶
Project layout¶
Under the folder userdocs mkdocs.yml # The configuration file. docs/ index.md # The documentation homepage. ... # Other markdown pages, images and other files.
Introducing Weave GitOps¶
"GitOps is the best thing since configuration as code. Git changed how we collaborate, but declarative configuration is the key to dealing with infrastructure at scale, and sets the stage for the next generation of management tools"
- Kelsey Hightower, Staff Developer Advocate, Google.
Weave GitOps improves developer experience—simplifying the complexities and cognitive load of deploying and managing cloud native apps on Kubernetes so that teams can go faster. It’s a powerful extension of Flux, a leading GitOps engine and Cloud Native Computing Foundation project. Weaveworks are the creators of Flux.
Weave GitOps’ intuitive user interface surfaces key information to help application operators easily discover and resolve issues—simplifying and scaling adoption of GitOps and continuous delivery. The UI provides a guided experience that helps users to easily discover the relationships between Flux objects and build understanding while providing insights into application deployments.
Today Weave GitOps defaults are Flux, Kustomize, Helm, SOPS, and Kubernetes Cluster API. If you use Flux already, then you can easily add Weave GitOps to create a platform management overlay.
Tip
Adopting GitOps can bring a number of key benefits—including faster and more frequent deployments, easy recovery from failures, and improved security and auditabiity. Check out our GitOps for Absolute Beginners eBook and Guide to GitOps for more information.
Getting Started¶
This user guide provides content that will help you to install and get started with our free and paid offerings: - Weave GitOps Open Source: a simple, open source developer platform for people who don't have Kubernetes expertise but who want cloud native applications. It includes the UI and many other features that take your team beyond a simple CI/CD system. Experience how easy it is to enable GitOps and run your apps in a cluster. Go here to install. - Weave GitOps Enterprise: an enterprise version that adds automation and 100% verifiable trust to existing developer platforms, enabling faster and more frequent deployments with guardrails and golden paths for every app team. Note that Enterprise offers a more robust UI than what you'll find in our open source version. Go here to install.
Tip
Want to learn more about how Weave GitOps Enterprise can help your team? Get in touch with sales@weave.works to discuss your needs.
Weave GitOps works on any Chromium-based browser (Chrome, Opera, Microsoft Edge), Safari, and Firefox. We only support the latest and prior two versions of these browsers.
To give Weave GitOps a test drive, we recommend checking out the Open Source version and its UI, then deploying an application. Let's take a closer look at the features it offers you, all for free.
Weave GitOps Open Source Features¶
Like our Enterprise version, Weave GitOps Open Source fully integrates with Flux as the GitOps engine to provide:
Some of the things you can do with it:
OK, time to install!
Monitoring ENTERPRISE¶
Weave GitOps Enterprise provides monitoring telemetry and tooling for metrics and profiling. WGE generates Prometheus metrics for monitoring both performance and business operations.
Setup¶
The following configuration options are available for you to configure monitoring:
---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+ name: weave-gitops-enterprise
+ namespace: flux-system
+spec:
+ values:
+ monitoring:
+ enabled: true # enable it if you want to expose a monitoring server
+ service:
+ name: monitoring
+ port: 8080 # port to expose the monitoring server
+ metrics:
+ enabled: true # enable it to expose a prometheus metrics endpoint in `/metrics`
+ profiling:
+ enabled: false # enable it to expose a pprof debug endpoint `/debug/pprof`
+Warning
The monitoring server holds private services, so you probably won't need to expose anything beyond your cluster. If you must, ensure that it is properly secured.
Get Started with Monitoring¶
This setup follows the same monitoring approach as Flux and is based on Prometheus Operator. Adapt it to your context as needed.
Expand to see manifest contents
apiVersion: source.toolkit.fluxcd.io/v1
+kind: GitRepository
+metadata:
+name: weave-gitops-quickstart
+namespace: flux-system
+spec:
+interval: 10m0s
+ref:
+ branch: main
+url: https://github.com/weaveworks/weave-gitops-quickstart
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+name: monitoring
+---
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+name: kube-prometheus-stack
+namespace: flux-system
+spec:
+interval: 10m0s
+sourceRef:
+ kind: GitRepository
+ name: weave-gitops-quickstart
+path: ./monitoring/kube-prometheus-stack
+prune: true
+targetNamespace: monitoring
+wait: true
+Expand to see manifest contents
apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+name: monitoring-config
+namespace: flux-system
+spec:
+interval: 10m0s
+sourceRef:
+ kind: GitRepository
+ name: weave-gitops-quickstart
+path: ./monitoring/weave-gitops
+dependsOn:
+ - name: kube-prometheus-stack
+prune: true
+targetNamespace: monitoring
+
Dashboards¶
Weave GitOps Overview
Monitor Weave GitOps golden signals for API server and controllers:
Weave GitOps Runtime
Monitor Weave GitOps Go runtime metrics like memory usage, memory heap, and Goroutines, among others.
Explorer
You can also monitor Explorer golden signals.
Profiling¶
During operations, profiling is useful for gaining a deeper understanding of how Weave GitOps runtime behaves. Given that Weave GitOps is written in Go, profiling happens through pprof. It is exposed as a web endpoint by pprof http.
Get Started with Profiling¶
Go here for more info on using pprof.
AWS Marketplace
AWS Marketplace¶
Weave GitOps is also available via the AWS Marketplace.
The following steps will allow you to deploy the Weave GitOps product to an EKS cluster via a Helm Chart.
These instructions presume you already have installed kubectl, eksctl, helm and the Helm S3 Plugin.
Step 1: Subscribe to Weave GitOps on the AWS Marketplace¶
To deploy the managed Weave GitOps solution, first subscribe to the product on AWS Marketplace.
Note: it may take ~20 minutes for your Subscription to become live and deployable.
Step 2: Configure an EKS Cluster¶
If you do not have a cluster on EKS, you can use eksctl to create one.
Copy the contents of the sample file below into cluster-config.yaml and replace the placeholder values with your settings. See the eksctl documentation for more configuration options.
Expand for file contents
cluster-config.yaml
---
+apiVersion: eksctl.io/v1alpha5
+kind: ClusterConfig
+metadata:
+name: CLUSTER_NAME # Change this
+region: REGION # Change this
+
+# This section is required
+iam:
+withOIDC: true
+serviceAccounts:
+- metadata:
+ name: wego-service-account # Altering this will require a corresponding change in a later command
+ namespace: flux-system
+ roleOnly: true
+ attachPolicy:
+ Version: "2012-10-17"
+ Statement:
+ - Effect: Allow
+ Action:
+ - "aws-marketplace:RegisterUsage"
+ Resource: '*'
+
+# This section will create a single Managed nodegroup with one node.
+# Edit or remove as desired.
+managedNodeGroups:
+- name: ng1
+instanceType: m5.large
+desiredCapacity: 1
+Create the cluster:
eksctl create cluster -f cluster-config.yaml
+In order to use the Weave GitOps container product, your cluster must be configured to run containers with the correct IAM Policies.
The recommended way to do this is via IRSA.
Use this eksctl configuration below (replacing the placeholder values) to: - Associate an OIDC provider - Create the required service account ARN
Save the example below as oidc-config.yaml
Expand for file contents
oidc-config.yaml
---
+apiVersion: eksctl.io/v1alpha5
+kind: ClusterConfig
+metadata:
+name: CLUSTER_NAME # Change this
+region: REGION # Change this
+
+# This section is required
+iam:
+withOIDC: true
+serviceAccounts:
+- metadata:
+ name: wego-service-account # Altering this will require a corresponding change in a later command
+ namespace: flux-system
+ roleOnly: true
+ attachPolicy:
+ Version: "2012-10-17"
+ Statement:
+ - Effect: Allow
+ Action:
+ - "aws-marketplace:RegisterUsage"
+ Resource: '*'
+eksctl utils associate-iam-oidc-provider -f oidc-config.yaml --approve
+eksctl create iamserviceaccount -f oidc-config.yaml --approve
+Step 3: Fetch the Service Account Role ARN¶
First retrieve the ARN of the IAM role which you created for the wego-service-account:
# replace the placeholder values with your configuration
+# if you changed the service account name from wego-service-account, update that in the command
+export SA_ARN=$(eksctl get iamserviceaccount --cluster <cluster-name> --region <region> | awk '/wego-service-account/ {print $3}')
+
+echo $SA_ARN
+# should return
+# arn:aws:iam::<account-id>:role/eksctl-<cluster-name>-addon-iamserviceaccount-xxx-Role1-1N41MLVQEWUOF
+This value will also be discoverable in your IAM console, and in the Outputs of the Cloud Formation template which created it.
Step 4: Install Weave GitOps¶
Copy the Chart URL from the Usage Instructions in AWS Marketplace, or download the file from the Deployment template to your workstation.
To be able to log in to your new installation, you need to set up authentication. Create a new file values.yaml where you set your username, and a bcrypt hash of your desired password, like so:
./values.yaml
gitops:
+ adminUser:
+ create: true
+ username: <UPDATE>
+ passwordHash: <UPDATE>
+Then install it:
helm install wego <URL/PATH> \
+--namespace=flux-system \
+--create-namespace \
+--set serviceAccountRole="$SA_ARN" \
+--values ./values.yaml
+helm install wego <URL/PATH> \
+--namespace=flux-system \
+--create-namespace \
+--set serviceAccountName='<name>' \
+--set serviceAccountRole="$SA_ARN" \
+--values ./values.yaml
+Step 5: Check your installation¶
Run the following from your workstation:
kubectl get pods -n flux-system
+# you should see something like the following returned
+flux-system helm-controller-5b96d94c7f-tds9n 1/1 Running 0 53s
+flux-system kustomize-controller-8467b8b884-x2cpd 1/1 Running 0 53s
+flux-system notification-controller-55f94bc746-ggmwc 1/1 Running 0 53s
+flux-system source-controller-78bfb8576-stnr5 1/1 Running 0 53s
+flux-system wego-metering-f7jqp 1/1 Running 0 53s
+flux-system ww-gitops-weave-gitops-5bdc9f7744-vkh65 1/1 Running 0 53s
+Your Weave GitOps installation is now ready!
Step 3: Deploy an Application¶
Now that you have a feel for how to navigate the dashboard, let's deploy a new application. In this section we will use podinfo as our sample web application.
Deploying podinfo¶
git clone https://github.com/$GITHUB_USER/fleet-infra
+cd fleet-infra
+flux create source git podinfo \
+ --url=https://github.com/stefanprodan/podinfo \
+ --branch=master \
+ --interval=30s \
+ --export > ./clusters/management/podinfo-source.yaml
+More information about GitRepository is available here.
If you get stuck here, try the ls command to list your files and directories. If that doesn’t work, try ls -l ./clusters.
git add -A && git commit -m "Add podinfo source"
+git push
+flux create kustomization podinfo \
+ --target-namespace=flux-system \
+ --source=podinfo \
+ --path="./kustomize" \
+ --prune=true \
+ --interval=5m \
+ --export > ./clusters/management/podinfo-kustomization.yaml
+git add -A && git commit -m "Add podinfo kustomization"
+git push
+View the Application in Weave GitOps¶
Flux will detect the updated fleet-infra and add podinfo. Navigate back to the dashboard to make sure that the podinfo application appears.
Click on podinfo to find details about the deployment. There should be two pods available.
Info
Podinfo comes with a HorizontalPodAutoscaler, which uses the metrics-server. We don't use the metrics-server in this tutorial, but note that it's the reason why HorizontalPodAutoscaler will report as Not ready in your dashboard. We recommend ignoring the warning.
Customize podinfo¶
To customize a deployment from a repository you don’t control, you can use Flux in-line patches. The following example shows how to use in-line patches to change the podinfo deployment.
Expand to see Kustomization patches
./clusters/management/podinfo-kustomization.yaml
---
+apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+kind: Kustomization
+metadata:
+ name: podinfo
+ namespace: flux-system
+spec:
+ interval: 60m0s
+ path: ./kustomize
+ prune: true
+ sourceRef:
+ kind: GitRepository
+ name: podinfo
+ targetNamespace: flux-system
+// highlight-start
+ patches:
+ - patch: |-
+ apiVersion: autoscaling/v2beta2
+ kind: HorizontalPodAutoscaler
+ metadata:
+ name: podinfo
+ spec:
+ minReplicas: 3
+ target:
+ name: podinfo
+ kind: HorizontalPodAutoscaler
+// highlight-end
+git add -A && git commit -m "Increase podinfo minimum replicas"
+git push
+
Suspend updates¶
Suspending updates to a kustomization allows you to directly edit objects applied from a kustomization, without your changes being reverted by the state in Git.
To suspend updates for a kustomization, from the details page, click on the suspend button at the top, and you should see it be suspended:
This shows in the applications view with a yellow warning status indicating it is now suspended
To resume updates, go back to the details page, click the resume button, and after a few seconds reconsolidation will continue.
Delete Podinfo¶
To delete Podinfo in the GitOps way, run this command from the root of your working directory:
rm ./clusters/management/podinfo-kustomization.yaml
+ rm ./clusters/management/podinfo-source.yaml
+ git add -A && git commit -m "Remove podinfo kustomization and source"
+ git push
+Complete!¶
Congratulations 🎉🎉🎉
You've now completed the getting started guide. We welcome any and all feedback, so please let us know how we could have made your experience better.
Step 1: Install Weave GitOps Open Source on Your Cluster¶
Tip
These instructions only apply to Weave GitOps Open Source. To install Weave GitOps Enterprise, go here.
This page covers Weave GitOps Open Source installation and is adapted from the Flux - Getting Started guide.
If you haven't already, please check out our Introduction to Weave GitOps page for additional information about Weave GitOps Open Source as well as our Enterprise version.
Prerequisites¶
Before you can install Weave GitOps Open Source, you will need:
We also recommend taking a look at the Flux Core Concepts page if you need to brush up on terminology.
Check your Cluster's Kubernetes Version¶
No matter which version of Weave GitOps you install, you need to have a Kubernetes cluster up and running. We test Weave GitOps against the latest supported Kubernetes releases.
Note that the version of Flux that you use might impose further minimum version requirements.
Install Flux¶
Weave GitOps is an extension to Flux. Therefore, it requires that Flux 0.32 or a later version has already been installed on your Kubernetes cluster. Full documentation is available here.
In this section we are going to do the following:
Let's get into it...
Install the Flux CLI¶
brew install fluxcd/tap/flux
+To upgrade to the latest version, run this command:
brew upgrade fluxcd/tap/flux
+We recommend upgrading the CLI before running bootstrap to upgrade the controllers with flux bootstrap.
Find which version is installed with flux -v, and use that for flux bootstrap --version=v<CLI-VERSION>.
With Bash, you can run sudo curl -s https://fluxcd.io/install.sh | sudo FLUX_VERSION=<VERSION> bash.
Tip
If you want to install an older version of Flux CLI, you can download the binary for your OS from the releases page.
For other installation methods, see the relevant Flux documentation.
Export your credentials¶
Ensure your PAT has repo scope.
export GITHUB_TOKEN=<your-token>
+export GITHUB_USER=<your-username>
+Check your Kubernetes cluster¶
flux check --pre
+The output is similar to:
► checking prerequisites
+✔ kubernetes 1.22.2 >=1.20.6
+✔ prerequisites checks passed
+Install Flux onto your cluster with the flux bootstrap command¶
flux bootstrap creates a flux system folder in your repository that includes the manifests Flux needs to operate. It also generates a key value pair for Flux to access the repo.
The command below assumes the Git provider is github. If you would rather use GitLab, change this to gitlab.
flux bootstrap github \
+ --owner=$GITHUB_USER \
+ --repository=fleet-infra \
+ --branch=main \
+ --path=./clusters/my-cluster \
+ --personal \
+ --components-extra image-reflector-controller,image-automation-controller
+Full installation documentation, including how to work with other Git providers, is available here.
Install the gitops CLI¶
Weave GitOps includes a command-line interface to help users create and manage resources. The gitops CLI is currently supported on Mac (x86 and Arm) and Linux, including Windows Subsystem for Linux (WSL). Windows support is a planned enhancement.
There are multiple ways to install the gitops CLI:
curl --silent --location "https://github.com/weaveworks/weave-gitops/releases/download/v0.36.0/gitops-$(uname)-$(uname -m).tar.gz" | tar xz -C /tmp
+sudo mv /tmp/gitops /usr/local/bin
+gitops version
+brew tap weaveworks/tap
+brew install weaveworks/tap/gitops
+Deploy Weave GitOps¶
In this section we will:
Clone your Git repository where Flux has been bootstrapped¶
git clone https://github.com/$GITHUB_USER/fleet-infra
+cd fleet-infra
+If you have difficulty saving the YAML to the correct path, run the command mkdir -p ./clusters/my-cluster.
Deploy¶
Run the following command, which will create a HelmRepository and HelmRelease to deploy Weave GitOps:
PASSWORD="<A new password you create, removing the brackets and including the quotation marks>"
+gitops create dashboard ww-gitops \
+ --password=$PASSWORD \
+ --export > ./clusters/my-cluster/weave-gitops-dashboard.yaml
+Warning
This command stores a hash of a password. This is relatively safe for demo and testing purposes, but we strongly recommend using a more secure method of storing secrets (such as Flux's SOPS integration) for production systems.
Our docs on securing access to the dashboard provide additional guidance and alternative login methods.
You will use the password you've just created when you've finished Weave GitOps Open Source installation and are ready to login to the dashboard UI.
Tip
If you need to customize the Weave GitOps Helm release, you can use the --values CLI flag to supply one or more values files.
Commit and push the weave-gitops-dashboard.yaml to the fleet-infra repository¶
git add -A && git commit -m "Add Weave GitOps Dashboard"
+git push
+Validate that Weave GitOps and Flux are installed¶
Note: this wont be instantaneous. Give the Flux controllers a couple of minutes to pull the latest commit.
kubectl get pods -n flux-system
+You should see something similar to:
NAME READY STATUS RESTARTS AGE
+helm-controller-5bfd65cd5f-gj5sz 1/1 Running 0 10m
+kustomize-controller-6f44c8d499-s425n 1/1 Running 0 10m
+notification-controller-844df5f694-2pfcs 1/1 Running 0 10m
+source-controller-6b6c7bc4bb-ng96p 1/1 Running 0 10m
+ww-gitops-weave-gitops-86b645c9c6-k9ftg 1/1 Running 0 5m
+If you wait for a while and still nothing happens, it might be that your manifests haven’t been exported to the repository. This means that Weave GitOps won't install.
Tip
You can use the Weave GitOps Helm Chart to customize your installation. Find the full Chart reference here.
Next steps¶
Now let's explore the Weave GitOps Open Source UI. Then, we'll deploy an application.
Optional: Running the UI on a Subpath
Running the UI on a subpath¶
By default, the UI is served on the root path /. It is possible to run the UI on a subpath, for example /weave-gitops. This is useful if you want to run weave-gitops alongside other applications on the same domain.
To run the UI on a subpath, you need to set the --route-prefix flag on the weave-gitops server. For example, if you want to run the UI on /weave-gitops, you can set the flag to --route-prefix=/weave-gitops.
To set the flag we use the additionalArgs field in the spec.values section of the weave-gitops HelmRelease.
spec:
+ values:
+ additionalArgs:
+ - --route-prefix=/weave-gitops
+Ingress¶
Ingress is a Kubernetes resource that allows you to expose your application to the internet. Please refer to the Kubernetes documentation for more information about a complete Ingress configuration. It often depends on the Kubernetes provider you are using and your particular setup.
The Weave GitOps Helm chart can generate an Ingress resource to integrate with the ingress controller you have configured for your cluster. To enable ingress generation set the ingress.enabled field to true.
spec:
+ values:
+ ingress:
+ enabled: true
+ hosts:
+ - host: ""
+ paths:
+ - path: /wego # set the path to `/` if you have not set the `--route-prefix` flag
+ pathType: Prefix
+See the Helm chart reference for a list of all supported ingress options.
Step 2: Explore the Weave GitOps Open Source UI¶
The Weave GitOps user interface enables you to manage and view all of your applications in one place. This documentation gives you an overview of the Weave GitOps Open Source UI.
Tip
To check out Weave GitOps Enterprise's UI, which provides an even richer user experience, please contact sales@weave.works.
Overview¶
A quick preview of what the Weave GitOps Open Source UI provides: * an Applications view that shows summary information from Kustomization and HelmRelease objects so that you can quickly understand the state of your deployments across a cluster. * a Sources view that shows summary information from gitrepository, helmrepository and bucket objects and tells you the current status of resources that are synchronizing content from where you’ve declared the desired state of your system—for example, Git repositories. * a Flux Runtime view that provides the status of the GitOps engine that continuously reconciles your desired and live state. It shows your installed GitOps Toolkit Controllers and version. * an Image Automation view that reduces GitOps friction, particularly in non-production environments, by enabling you to discover repositories, policies, and updates on your cluster. Deploy the latest image in a dev or staging environment with minimal fuss, and keep your platform updated with the latest approved versions—for example, patch releases to reduce exposure to CVEs. Auto-deploy when approval is gated before the image is added to an internal registry. * A Notifications View that leverages Flux's notification controller to show which notifications are already configured within the UI. This enables WeGO users to set up and receive notifications from Weave GitOps. Here you can find the list of providers. If you’re a platform operator, this view will help you to understand your egress topology across clusters so you’ll know where events are being sent beyond your clusters. * multiple views for debugging. * a dark mode option.
It also enables you to: * sync your latest Git commits directly from the UI * leverage Kubernetes RBAC to control permissions in the dashboard
Let's dive in.
Login to the GitOps Dashboard¶
First, expose the service running on the cluster with this command:
kubectl port-forward svc/ww-gitops-weave-gitops -n flux-system 9001:9001
+Next, open the dashboard and login using either the emergency cluster user or OIDC, based on your configuration. (Note: The same directions for WGE apply to OSS for this step.) If you followed the example above, the emergency user will be configured with the username set to admin. This means that you can use “admin” as your user name, and the password that you set earlier during installation as $PASSWORD.
The label of the OIDC button on the login screen is configurable via a feature flag environment variable. This can give your users a more familiar experience when logging in.
Adjust the configuration in the Helm values.yaml file or the spec.values section of the Weave GitOps HelmRelease resource:
envVars:
+ - name: WEAVE_GITOPS_FEATURE_OIDC_BUTTON_LABEL
+ value: "Login with ACME"
+The Applications View¶
Upon login you're taken to the Applications view, which allows you to quickly understand the state of your deployments and shows summary information from Kustomization and HelmRelease objects. You can apply dark mode using the toggle switch in the top right corner.
In the above screenshot you can see: - two Kustomizations called podinfo and canaries corresponding to the applications with the same names. The source referenced by podinfo is shipping-service-podinfo which has been verified whereas the one referenced by canaries does not have verification set up. - three HelmReleases called weave-gitops-enterprise, tf-controller and podinfo which deploys the respective Helm Charts.
The table view shows you the reported status so you can understand whether a reconciliation has been successful, and when it was last updated. You can also see where the Flux objects are deployed, which Source object they are reconciling from and whether or not that Source is verified (this requires verification to have been set up for the source). Clicking the name of the Source will take you to a detail view for the given Source object. The view automatically updates every few seconds so you know the current state of your system.
Tip
For more information about Sources, please take a look at the Flux documentation.
For information on Source verification, you can check: - Flux documentation - GitRepository verification - Flux documentation - OCIRepository verification
If verification is not set up for the repository, this will appear blank in the UI.
More actions you can take: * Click the magnifying glass icon to search for and filter objects by Name. * Filter by Type by clicking the strawberry icon to its right. * Click the Name of an object to get a detailed view for the given Kustomization or HelmRelease. (You'll see this again in the Sources view.) * In the main Applications view, you can use the checkbox to the left of your listed applications to select them and perform actions from the actions menu at the top. These actions are Sync (reconcile), Suspend, and Resume, and they affect Flux resources.
A Closer Look: Exploring the flux-system Deployment¶
Let's explore the flux-system Kustomization. Navigate back to the Applications view, and click on the flux-system object.
It might take a few moments for the data to load. Once it does, you should get a result that resembles the above screenshot. Here you can find key information about how the resource is defined: * which Source it is reading from * the latest applied commit * the exact path with the Source repository that is being deployed * the Interval where Flux will look to reconcile any differences between the declared and live state. For example, if a kubectl patch has been applied on the cluster, it will effectively be reverted. If a longer error message is reported by this object, you'll be able to see it in its entirety on this page.
Underneath the summary information you'll find:
Events tab 
Reconciliation Graph tab 
Yaml tab 
The Sources View¶
In the left-hand menu of the UI, click on the Sources view. This will show you where Flux pulls its application definitions from—for example, Git repositories—and the current state of that synchronization. Sources shows summary information from GitRepository, HelmRepository, HelmChart, and Bucket objects.
In the above screenshot you can see: - a GitRepository called shipping-service-podinfo - an OCIRepository called podinfo-oci
These have both had verification set up on them which has been completed successfully.
The Sources table view displays information about status so that you can see whether Flux has been able to successfully pull from a given source, and which specific commit was last detected. It shows you key information like the Interval—namely, how frequently Flux will check for updates in a given source location. You can also see whether or not that source is verified (if this is something that you have set up for the specific source).
Actions you can take: * Apply filtering as you did the Applications view. * Click a URL to navigate to a given source—i.e. a repository in GitHub—or the Name of a Source to view more details about it.
Go back to the Details tab, and click GitRepository/flux-system from the summary at the top of the page.
As with an Application detail view, you can see key information about how the resource is defined.
The Image Automation View¶
Maybe you're an app developer who wants to deploy the latest image in a dev/staging environment with as minimal fuss as possible and reduce GitOps friction. Or you might be a platform engineer who wants to keep your platform up-to-date with the latest approved versions—for example, patch releases to reduce exposure to CVEs—or auto-deploy when approval is gated before adding an image to an internal registry. The Image Automation view can help.
WeGO's Image Automation view allows users to configure automatic updates to their workloads based on the detection of a new image tag in a repository. For application developers, this means faster deployments and shorter feedback cycles to easily verify changes to an application in a Kubernetes environment. The view still supports GitOps workflows as the changes are committed back to Git—either to the branch already reconciled by Flux, or to an alternative branch so that a Pull Request can be generated and peer review can occur.
Image Automation refers to Flux's ability to update the image tag specified in a manifest based on detection of a newer image and automatically deploy to a cluster. It involves three required objects—ImageRepositories, ImagePolicies, and ImageUpdateAutomations—which WeGO OSS users can discover on their clusters. Users can also view object details either through a YAML-like view, as we do for most non-Flux objects, or a details view. The UI makes it possible to suspend or resume ImageRepositories and ImageUpdateAutomations so that Flux stops looking for new updates or committing these to Git. Also, the UI shows whether all required resources are configured and assists with Image Policy to show the latest image.
ImageRepositories, ImagePolicies, and ImageUpdateAutomations are used by Flux's Image Automation Controllers. The Image Reflector controller and the Image Automation controller work together to update a Git repository when new container images are available. In WeGO OSS, if the image-reflector-controller and or image-automation-controller are not installed on a cluster, a warning message will display.
If you make a mistake configuring one of the resources, you can use WeGO to easily trace from the Image Repository scan, see whether it is able to select the image based on the Image Policy, and detect whether an Image Update has successfully run. This provides greater visibility into the machinery provided by Flux and enables quicker troubleshooting than what's possible by hunting via the Flux CLI. App devs can triage issues without depending on their platform teams.
The Flux Runtime View¶
Let's go back to the left-hand menu of the UI and click on Flux Runtime. This view provides information on the GitOps engine, which continuously reconciles your desired and live state, and helps users to know which apiVersion to use in manifests. It comes with two tabs: one for controllers, and other for custom resource definitions (CRDs).
Controllers¶
The Controllers tab shows your installed GitOps Toolkit Controllers and their version.
By default, flux bootstrap will install the following controllers: - helm-controller - kustomize-controller - notification-controller - source-controller
From this view you can see whether the controllers are healthy and which version of a given component is currently deployed.
CRDs¶
The CRD tab lists the custom resources that the GitOps Toolkit Controllers use. This allows you to see which resources you will be able to create.
Moving On¶
Now that we are familiar with the dashboard, let's deploy a new application .
Authorization ENTERPRISE¶
Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
To view pipelines, users need read access to the pipeline resource and the underlying application resources. This sample configuration shows a recommended way to configure RBAC to provide such access. The pipeline-reader role and the search-pipeline-reader role-binding allow a group search-developer to access pipeline resources within the search namespace.
apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+ name: pipeline-reader
+rules:
+ - apiGroups: [ "pipelines.weave.works" ]
+ resources: [ "pipelines" ]
+ verbs: [ "get", "list", "watch"]
+ - apiGroups: ["helm.toolkit.fluxcd.io"]
+ resources: [ "helmreleases" ]
+ verbs: [ "get", "list", "watch"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+ name: search-pipeline-reader
+ namespace: search
+subjects:
+ - kind: Group
+ name: search-developer
+ apiGroup: rbac.authorization.k8s.io
+roleRef:
+ kind: ClusterRole
+ name: pipeline-reader
+ apiGroup: rbac.authorization.k8s.io
+Pipelines ENTERPRISE¶
Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
Weave GitOps Enterprise Pipelines enables teams to increase the velocity, stability, and security of software systems via automated deployment pipelines. It provides insights into new application versions that are being rolled out across clusters and environments, which allows you to implement security guardrails and track metrics to assess if the application is working as desired. In instances of failures, the change is abandoned with an automatic rollout of the older version.
With Pipelines, you define a release pipeline for a given application as a custom resource. The pipeline can comprise any number of environments through which an application is expected to be deployed. Push a change to your application in your dev environment, for example, and watch the update roll out across staging and production environments all from a single PR (or an external process like Jenkins)—with Weave GitOps Enterprise orchestrating everything.
Designed with flexibility in mind, Pipelines can be easily integrated within your existing CI setup—for example, CircleCI, Jenkins, Tekton, or GitHub Actions.
Benefits to Developers¶
The Pipelines feature: - reduces toil and errors when setting up a new pipeline or reproducing previous pipelines through YAML constructs - saves time and overhead with automated code rollout from one environment to another, with minimal intervention from the Ops team - enables users to observe code progression and track application versions through different environments from the Weave GitOps UI - streamlines code deployment from one environment to another, and minimizes friction between application development and Ops teams - enables you to easily define which Helm charts are part of the environments you create—saving lots of time through automated package management
Now that you know what delivery pipelines can do for you, follow the guide to get started.
Getting Started with Pipelines ENTERPRISE¶
Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
Prerequisites¶
Before using Pipelines, please ensure that: - You have Weave GitOps Enterprise installed on a cluster. - You have configured Weave GitOps Enterprise RBAC for Pipelines. - The Pipelines feature flag enablePipelines has been enabled. This flag is part of the Weave GitOps Enterprise Helm chart values and is enabled by default. - Any leaf clusters running workloads that you need to visualise using Pipelines have been added to Weave GitOps Enterprise. - You have exposed the promotion webhook on the management cluster and leaf clusters can reach that webhook endpoint over the network.
Define a Pipeline¶
A pipeline allows you to define the route your application is taking, so that you can get it to production. Three main concepts are at play: - the application to deliver - the environments that your app will go through on its way to production (general). An environment describes the different stages of a pipeline and consists of one or more deployment targets. - the deployment targets, the clusters that each environment has. A deployment target consists of a namespace and a GitOpsCluster reference and is used to specify where the application is running in your fleet.
You can define a delivery pipeline using a Pipeline custom resource. An example of such a CR is shown here:
Expand to view
---
+apiVersion: pipelines.weave.works/v1alpha1
+kind: Pipeline
+metadata:
+name: podinfo-02
+namespace: flux-system
+spec:
+appRef:
+ apiVersion: helm.toolkit.fluxcd.io/v2beta1
+ kind: HelmRelease
+ name: podinfo
+environments:
+ - name: dev
+ targets:
+ - namespace: podinfo-02-dev
+ clusterRef:
+ kind: GitopsCluster
+ name: dev
+ namespace: flux-system
+ - name: test
+ targets:
+ - namespace: podinfo-02-qa
+ clusterRef:
+ kind: GitopsCluster
+ name: dev
+ namespace: flux-system
+ - namespace: podinfo-02-perf
+ clusterRef:
+ kind: GitopsCluster
+ name: dev
+ namespace: flux-system
+ - name: prod
+ targets:
+ - namespace: podinfo-02-prod
+ clusterRef:
+ kind: GitopsCluster
+ name: prod
+ namespace: flux-system
+In the example above, the podinfo application is delivered to a traditional pipeline composed of dev, test, and prod environments. In this case, the test environment consists of two deployment targets, qa and perf. This is to indicate that, although both targets are part of the same stage (testing), they can evolve separately and may run different versions of the application. Note that two clusters, dev and prod, are used for the environments; both are defined in the flux-system namespace.
For more details about the spec of a pipeline, go here.
View Your List of Pipelines¶
Once Flux has reconciled your pipeline, you can navigate to the Pipelines view in the WGE UI to see the list of pipelines to which you have access.
For each pipeline, the WGE UI shows a simplified view with the application Type and Environments it goes through.
View Pipeline Details¶
Once you have selected a pipeline from the list, navigate to its details view where you can see the current status of your application by environment and deployment target.
Using GitOpsTemplates for Pipelines ENTERPRISE¶
To create new Pipelines and their required resources from within Weave GitOps Enterprise, you can leverage GitOpsTemplates, which help platform teams scale for developer self-service.
This document provides example configuration that you can adapt and use within your own organization, based on your tenancy model.
We will cover the creation of:
Secrets, required for authentication and authorization between leaf and management clusters as well as to Git, are out of scope for this document and must be handled by your chosen secret management solution.
For advice on Secrets Management, refer to the Flux guide.
Templates can include a single resource or multiple resources, depending on your use case. For example, you may want to only create the Pipeline custom resource to associate existing HelmReleases. Or, you can create the HelmReleases, notification controller resources, and Pipeline all in a single template. They are highly customizable to meet the needs of your teams.
Adding New Resources From Within the Weave GitOps Enterprise Dashboard¶
GitOpsTemplates are custom resources installed onto a management cluster where Weave GitOps Enterprise resides. To add a new Pipeline, click Create a Pipeline from within the Pipeline view. This will take you to a pre-filtered list of templates with the label: weave.works/template-type: pipeline.
The Templates view (shown below) lists all templates for which a given user has the appropriate permission to view. You can install GitOpsTemplates into different namespaces and apply standard Kubernetes RBAC to limit which teams can utilize which templates. You can also configure policy to enforce permitted values within a template.
Example: GitOpsTemplates¶
This section provides examples to help you build your own templates for Pipelines.
Pipeline: Visualization Only¶
Included Sample
This default template is shipped with Weave GitOps Enterprise to help you get started with Pipelines.
For flexibility, this allows the template user to specify the names of the clusters where the application is deployed, and to vary the namespace per cluster. This works even in a tenancy model where environments coexist on the same cluster and use namespaces for isolation.
Expand to view example template
---
+apiVersion: templates.weave.works/v1alpha2
+kind: GitOpsTemplate
+metadata:
+name: pipeline-sample
+namespace: default # Namespace where the GitOpsTemplate is installed, consider that a team will need READ access to this namespace and the custom resource
+labels:
+ weave.works/template-type: pipeline
+spec:
+description: Sample Pipeline showing visualization of two helm releases across two environments.
+params:
+ - name: RESOURCE_NAME # This is a required parameter name to enable Weave GitOps to write to your Git Repository
+ description: Name of the Pipeline
+ - name: RESOURCE_NAMESPACE
+ description: Namespace for the Pipeline on the management cluster
+ default: flux-system # default values make it easier for users to fill in a template
+ - name: FIRST_CLUSTER_NAME
+ description: Name of GitopsCluster object for the first environment
+ - name: FIRST_CLUSTER_NAMESPACE
+ description: Namespace where this object exists
+ default: default
+ - name: FIRST_APPLICATION_NAME
+ description: Name of the HelmRelease for your application in the first environment
+ - name: FIRST_APPLICATION_NAMESPACE
+ description: Namespace for this application
+ default: flux-system
+ - name: SECOND_CLUSTER_NAME
+ description: Name of GitopsCluster object for the second environment
+ - name: SECOND_CLUSTER_NAMESPACE
+ description: Namespace where this object exists
+ default: default
+ - name: SECOND_APPLICATION_NAME
+ description: Name of the HelmRelease for your application in the second environment
+ - name: SECOND_APPLICATION_NAMESPACE
+ description: Namespace for this application
+ default: flux-system
+resourcetemplates:
+ - content:
+ - apiVersion: pipelines.weave.works/v1alpha1
+ kind: Pipeline
+ metadata:
+ name: ${RESOURCE_NAME}
+ namespace: ${RESOURCE_NAMESPACE}
+ spec:
+ appRef:
+ apiVersion: helm.toolkit.fluxcd.io/v2beta1
+ kind: HelmRelease
+ name: ${APPLICATION_NAME}
+ environments:
+ - name: First-Environment
+ targets:
+ - namespace: ${FIRST_APPLICATION_NAMESPACE}
+ clusterRef:
+ kind: GitopsCluster
+ name: ${FIRST_CLUSTER_NAME}
+ namespace: ${FIRST_CLUSTER_NAMESPACE}
+ - name: Second-Environment
+ targets:
+ - namespace: ${SECOND_APPLICATION_NAMESPACE}
+ clusterRef:
+ kind: GitopsCluster
+ name: ${SECOND_CLUSTER_NAME}
+ namespace: ${SECOND_CLUSTER_NAMESPACE}
+Pipeline - Multi-Cluster Promotion¶
This example extends the above to add a promotion strategy. In this case, it will raise a pull request to update the application version in subsequent environments.
Expand to view example template
---
+apiVersion: templates.weave.works/v1alpha2
+kind: GitOpsTemplate
+metadata:
+name: pipeline-sample
+namespace: default
+labels:
+ weave.works/template-type: pipeline
+spec:
+description: Sample Pipeline showing visualization of two helm releases across two environments.
+params:
+ - name: RESOURCE_NAME
+ description: Name of the Pipeline
+ - name: RESOURCE_NAMESPACE
+ description: Namespace for the Pipeline on the management cluster
+ default: flux-system
+ - name: FIRST_CLUSTER_NAME
+ description: Name of GitopsCluster object for the first environment
+ - name: FIRST_CLUSTER_NAMESPACE
+ description: Namespace where this object exists
+ default: default
+ - name: FIRST_APPLICATION_NAME
+ description: Name of the HelmRelease for your application in the first environment
+ - name: FIRST_APPLICATION_NAMESPACE
+ description: Namespace for this application
+ default: flux-system
+ - name: SECOND_CLUSTER_NAME
+ description: Name of GitopsCluster object for the second environment
+ - name: SECOND_CLUSTER_NAMESPACE
+ description: Namespace where this object exists
+ default: default
+ - name: SECOND_APPLICATION_NAME
+ description: Name of the HelmRelease for your application in the second environment
+ - name: SECOND_APPLICATION_NAMESPACE
+ description: Namespace for this application
+ default: flux-system
+ - name: APPLICATION_REPO_URL
+ description: URL for the git repository containing the HelmRelease objects
+ - name: APPLICATION_REPO_BRANCH
+ description: Branch to update with new version
+ - name: GIT_CREDENTIALS_SECRET
+ description: Name of the secret in RESOURCE_NAMESPACE containing credentials to create pull requests
+resourcetemplates:
+ - content:
+ - apiVersion: pipelines.weave.works/v1alpha1
+ kind: Pipeline
+ metadata:
+ name: ${RESOURCE_NAME}
+ namespace: ${RESOURCE_NAMESPACE}
+ spec:
+ appRef:
+ apiVersion: helm.toolkit.fluxcd.io/v2beta1
+ kind: HelmRelease
+ name: ${APPLICATION_NAME}
+ environments:
+ - name: First-Environment
+ targets:
+ - namespace: ${FIRST_APPLICATION_NAMESPACE}
+ clusterRef:
+ kind: GitopsCluster
+ name: ${FIRST_CLUSTER_NAME}
+ namespace: ${FIRST_CLUSTER_NAMESPACE}
+ - name: Second-Environment
+ targets:
+ - namespace: ${SECOND_APPLICATION_NAMESPACE}
+ clusterRef:
+ kind: GitopsCluster
+ name: ${SECOND_CLUSTER_NAME}
+ namespace: ${SECOND_CLUSTER_NAMESPACE}
+ promotion:
+ pull-request:
+ url: ${APPLICATION_REPO_URL}
+ baseBranch: ${APPLICATION_REPO_BRANCH}
+ secretRef:
+ name: ${GIT_CREDENTIALS_SECRET}
+Git Credentials¶
For guidance on configuring credentials, find instructions in the Promoting Applications documentation.
Promotion Marker Added to HelmRelease in Second-Environment¶
You must add a comment to the HelmRelease or Kustomization patch where the spec.chart.spec.version is defined. For example, if the values used in the above template were as follows:
RESOURCE_NAME=my-app
+RESOURCE_NAMESPACE=pipeline-01
+Then the marker would be:
# {"$promotion": "pipeline-01:my-app:Second-Environment"}
+Find more guidance on adding markers here.
Alerts and Providers¶
This example shows you how you can configure multiple resources in a single template and simplify creation through common naming strategies. The notification controller communicates update events from the leaf clusters where applications are deployed to the management cluster, where the Pipeline Controller resides and orchestrates.
For the Alert, this template filters events to detect when an update has occurred. Depending on your use case, you can use different filtering.
For the Provider, this template uses authenticated (HMAC) communication to the promotion endpoint, where a secret must be present on both the management cluster and the leaf cluster(s). For simplicity's sake, you can use a generic provider instead; this will not require the secret.
Expand to view example template
---
+apiVersion: templates.weave.works/v1alpha2
+kind: GitOpsTemplate
+metadata:
+name: pipeline-notification-resources
+namespace: default
+labels:
+ weave.works/template-type: application # These are generic Flux resources rather than Pipeline-specific
+spec:
+description: Creates flux notification controller resources for a cluster, required for promoting applications via pipelines.
+params:
+ - name: RESOURCE_NAME
+ description: Name for the generated objects, should match the target Application (HelmRelease) name.
+ - name: RESOURCE_NAMESPACE
+ description: Namespace for the generated objects, should match the target Application (HelmRelease) namespace.
+ - name: PROMOTION_HOST
+ description: Host for the promotion webhook on the management cluster, i.e. "promotions.example.org"
+ - name: SECRET_REF
+ description: Name of the secret containing HMAC key in the token field
+ - name: ENV_NAME
+ description: Environment the cluster is a part of within a pipeline.
+resourcetemplates:
+ - content:
+ - apiVersion: notification.toolkit.fluxcd.io/v1beta1
+ kind: Provider
+ metadata:
+ name: ${RESOURCE_NAME}
+ namespace: ${RESOURCE_NAMESPACE}
+ spec:
+ address: http://${PROMOTION_HOST}/promotion/${APP_NAME}/${ENV_NAME}
+ type: generic-hmac
+ secretRef: ${SECRET_REF}
+ - apiVersion: notification.toolkit.fluxcd.io/v1beta1
+ kind: Alert
+ metadata:
+ name: ${RESOURCE_NAME}
+ namespace: ${RESOURCE_NAMESPACE}
+ spec:
+ providerRef:
+ name: ${RESOURCE_NAME}
+ eventSeverity: info
+ eventSources:
+ - kind: HelmRelease
+ name: ${RESOURCE_NAME}
+ exclusionList:
+ - ".*upgrade.*has.*started"
+ - ".*is.*not.*ready"
+ - "^Dependencies.*"
+s
Summary¶
GitOpsTemplates provide a highly flexible way for platform and application teams to work together with Pipelines.
You can hard-code values, offer a range of accepted values, or allow the template consumer to provide input based on your organization's requirements.
Templates are subject to RBAC as with any Kubernetes resource, enabling you to easily control which tenants have access to which templates.
For full details on GitOpsTemplates, read our documentation.
Setting Up Pipelines to Notify a Jenkins Webhook ENTERPRISE¶
Using Flux's Notification Controller, a Jenkins Webhook can be invoked on Pipeline promotion events.
Configuring Jenkins¶
To enable external callers to trigger a build on a job, an additional "Generic Webhook Trigger" plugin is required as Jenkins does not have this functionality built-in.
After the plugin is installed a new "Generic Webhook Trigger" job configuration option is available.
The only mandatory field is the "Token". Without this token, Jenkins will not know which build should be triggered.
Post content parameters¶
To access fields from the pipeline event payload, each field has to be defined as a "Post content parameters".
Expand to see an example Promotion Event payload
{
+"involvedObject": {
+ "kind": "Pipeline",
+ "namespace": "flux-system",
+ "name": "podinfo-pipeline",
+ "uid": "74d9e3b6-0269-4c12-9051-3ce8cfb7886f",
+ "apiVersion": "pipelines.weave.works/v1alpha1",
+ "resourceVersion": "373617"
+},
+"severity": "info",
+"timestamp": "2023-02-08T12:34:13Z",
+"message": "Promote pipeline flux-system/podinfo-pipeline to prod with version 6.1.5",
+"reason": "Promote",
+"reportingController": "pipeline-controller",
+"reportingInstance": "chart-pipeline-controller-8549867565-7822g"
+}
+Configure Notification Provider¶
In order to be able to invoke a generic webhook, a notification provider has to be defined. Jenkins expects the secret token which you configured above as a GET parameter or in the request header. The secret token can be stored in a Secret:
apiVersion: v1
+kind: Secret
+type: Opaque
+metadata:
+ name: jenkins-token
+ namespace: podinfo
+stringData:
+ headers: |
+ token: epicsecret
+Now we can define a Notification Provider using this secret:
apiVersion: notification.toolkit.fluxcd.io/v1beta1
+kind: Provider
+metadata:
+ name: jenkins-promotion
+ namespace: podinfo
+spec:
+ type: generic
+ address: https://jenkins.domain.tld/generic-webhook-trigger/invoke
+ secretRef:
+ name: jenkins-token
+Set Up Alerts¶
We can configure an Alert to use the jenkins-promotion provider. For example an Alert for the podinfo-pipeline in the flux-system namespace:
apiVersion: notification.toolkit.fluxcd.io/v1beta1
+kind: Alert
+metadata:
+ name: podinfo-pipeline-promotion
+ namespace: podinfo
+spec:
+ eventSeverity: info
+ eventSources:
+ - kind: Pipeline
+ name: podinfo-pipeline
+ namespace: flux-system
+ providerRef:
+ name: jenkins-promotion
+Setting up Pipelines to Trigger a Tekton Pipeline ENTERPRISE¶
Using Flux's Notification Controller, a Tekton EventListener can be triggered on Pipeline promotion events.
Configuring Tekton Pipelines¶
Tekton Tasks¶
In this tutorial, we have two tasks to demonstrate how to use parameter values from the Pipeline event payload. Both tasks print out messages with information about the pipeline promotion. Each task has three parameters: name, namespace, and message.
---
+apiVersion: tekton.dev/v1beta1
+kind: Task
+metadata:
+ name: hello
+ namespace: ww-pipeline
+spec:
+ params:
+ - name: name
+ type: string
+ - name: namespace
+ type: string
+ - name: message
+ type: string
+ steps:
+ - name: echo
+ image: alpine
+ script: |
+ #!/bin/sh
+ echo "Hello $(params.namespace)/$(params.name)!"
+ echo "Message: $(params.message)"
+---
+apiVersion: tekton.dev/v1beta1
+kind: Task
+metadata:
+ name: goodbye
+ namespace: ww-pipeline
+spec:
+ params:
+ - name: name
+ type: string
+ - name: namespace
+ type: string
+ - name: message
+ type: string
+ steps:
+ - name: goodbye
+ image: ubuntu
+ script: |
+ #!/bin/bash
+ echo "Goodbye $(params.namespace)/$(params.name)!"
+ echo "Message: $(params.message)"
+Tekton Pipeline¶
The hello-goodbye Tekton Pipeline has the same three parameters as the tasks and it passes down the values to them.
---
+apiVersion: tekton.dev/v1beta1
+kind: Pipeline
+metadata:
+ name: hello-goodbye
+ namespace: ww-pipeline
+spec:
+ params:
+ - name: name
+ type: string
+ - name: namespace
+ type: string
+ - name: message
+ type: string
+ tasks:
+ - name: hello
+ taskRef:
+ name: hello
+ params:
+ - name: namespace
+ value: $(params.namespace)
+ - name: name
+ value: $(params.name)
+ - name: message
+ value: $(params.message)
+ - name: goodbye
+ runAfter:
+ - hello
+ taskRef:
+ name: goodbye
+ params:
+ - name: namespace
+ value: $(params.namespace)
+ - name: name
+ value: $(params.name)
+ - name: message
+ value: $(params.message)
+Configuring Tekton Pipline Automation¶
In order to be able to trigger a Pipeline from an external source, we need three Tekton resources.
Tekton TriggerBinding¶
A JSON payload from the Notification Service about a Pipeline promotion looks like this:
{
+ "involvedObject": {
+ "kind": "Pipeline",
+ "namespace": "flux-system",
+ "name": "podinfo-pipeline",
+ "uid": "74d9e3b6-0269-4c12-9051-3ce8cfb7886f",
+ "apiVersion": "pipelines.weave.works/v1alpha1",
+ "resourceVersion": "373617"
+ },
+ "severity": "info",
+ "timestamp": "2023-02-08T12:34:13Z",
+ "message": "Promote pipeline flux-system/podinfo-pipeline to prod with version 6.1.5",
+ "reason": "Promote",
+ "reportingController": "pipeline-controller",
+ "reportingInstance": "chart-pipeline-controller-8549867565-7822g"
+}
+In our tasks, we are using only the involvedObject.name, involvedObject.namespace and message fields:
---
+apiVersion: triggers.tekton.dev/v1beta1
+kind: TriggerBinding
+metadata:
+ name: ww-pipeline-binding
+ namespace: ww-pipeline
+spec:
+ params:
+ - name: namespace
+ value: $(body.involvedObject.namespace)
+ - name: name
+ value: $(body.involvedObject.name)
+ - name: message
+ value: $(body.message)
+Tekton TriggerTemplate¶
The template has the same parameters as the Pipeline resources:
---
+apiVersion: triggers.tekton.dev/v1beta1
+kind: TriggerTemplate
+metadata:
+ name: ww-pipeline-template
+ namespace: ww-pipeline
+spec:
+ params:
+ - name: namespace
+ default: "Unknown"
+ - name: name
+ default: "Unknown"
+ - name: message
+ default: "no message"
+ resourcetemplates:
+ - apiVersion: tekton.dev/v1beta1
+ kind: PipelineRun
+ metadata:
+ generateName: hello-goodbye-run-
+ spec:
+ pipelineRef:
+ name: hello-goodbye
+ params:
+ - name: name
+ value: $(tt.params.name)
+ - name: namespace
+ value: $(tt.params.namespace)
+ - name: message
+ value: $(tt.params.message)
+Tekton EventListener¶
To access all required resources, we need an extra service account:
---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+ name: tekton-ww-pipeline-robot
+ namespace: ww-pipeline
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+ name: triggers-example-eventlistener-binding
+ namespace: ww-pipeline
+subjects:
+- kind: ServiceAccount
+ name: tekton-ww-pipeline-robot
+ namespace: ww-pipeline
+roleRef:
+ apiGroup: rbac.authorization.k8s.io
+ kind: ClusterRole
+ name: tekton-triggers-eventlistener-roles
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+ name: triggers-example-eventlistener-clusterbinding
+subjects:
+- kind: ServiceAccount
+ name: tekton-ww-pipeline-robot
+ namespace: ww-pipeline
+roleRef:
+ apiGroup: rbac.authorization.k8s.io
+ kind: ClusterRole
+ name: tekton-triggers-eventlistener-clusterroles
+With this ServiceAccount, we can create the EventListener using the TriggerBinding and TriggerTemplate:
---
+apiVersion: triggers.tekton.dev/v1beta1
+kind: EventListener
+metadata:
+ name: ww-pipeline-listener
+ namespace: ww-pipeline
+spec:
+ serviceAccountName: tekton-ww-pipeline-robot
+ triggers:
+ - name: ww-pipeline-trigger
+ bindings:
+ - ref: ww-pipeline-binding
+ template:
+ ref: ww-pipeline-template
+At this point, we should have a Service for our EventListener.
❯ kubectl get service -n ww-pipeline
+NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
+el-ww-pipeline-listener ClusterIP 10.96.250.23 <none> 8080/TCP,9000/TCP 3d
+Configure Notification Provider¶
In this case, we are using Tekton in the same cluster, so we can use an internal address to access the EventListener service. If they are not in the same cluster, exposing the service may be required through an ingress or a service mesh.
---
+apiVersion: notification.toolkit.fluxcd.io/v1beta1
+kind: Provider
+metadata:
+ name: tekton-promotion
+ namespace: hello-podinfo
+spec:
+ type: generic
+ address: http://el-ww-pipeline-listener.ww-pipeline:8080/
+Set Up Alerts¶
We can configure an Alert to use the tekton-promotion provider. For example, an Alert for the podinfo-pipeline in the flux-system namespace:
---
+apiVersion: notification.toolkit.fluxcd.io/v1beta1
+kind: Alert
+metadata:
+ name: tekton-promotion-podinfo
+ namespace: hello-podinfo
+spec:
+ eventSeverity: info
+ eventSources:
+ - kind: Pipeline
+ name: hello-podinfo
+ namespace: flux-system
+ providerRef:
+ name: tekton-promotion
+Promoting applications through pipeline environments¶
Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
Pipelines allow you to configure automatic promotions of applications through a consecutive set of environments, e.g. from dev to staging to production. The environments are defined in the Pipeline resource itself so that each pipeline governs a single application and all the environments to which it is deployed.
Info
At the moment only applications defined as Flux HelmReleases are supported in automatic promotions.
The Getting Started Guide describes how to create a basic pipeline for an application so you can visualize its deployments across a series of environments. You may also configure a pipeline in order to promote applications across a series of environments. There are currently two supported strategies for application promotions:
Before configuring any of the above promotion strategies, you need to setup notifications from all your environments so that whenever a new version gets deployed, the promotion webhook component of the pipeline controller is notified and takes an action based on the pipeline definition. The rest of this guide describes the configuration needed to setup application promotion via pipelines.
Expose the promotion webhook¶
Applications deployed in leaf clusters use the Flux notification controller running on each leaf cluster, to notify the management cluster of a successful promotion. This requires network connectivity to be established between the leaf cluster and the management cluster.
The component responsible for listening to incoming notifications from leaf clusters is the pipeline controller. It hosts a webhook service that needs to be exposed via an ingress resource to make it available for external calls. Exposing the webhook service is done via the Weave GitOps Enterprise Helm chart values and the configuration used depends on your environment. The example below shows the configuration for NGINX ingress controller and needs to be adjusted if another ingress controller is used:
spec:
+ values:
+ enablePipelines: true
+ pipeline-controller:
+ promotion:
+ ingress:
+ enabled: true
+ className: nginx
+ annotations:
+ cert-manager.io/cluster-issuer: letsencrypt
+ hosts:
+ - host: promotions.example.org
+ paths:
+ - path: /?(.*)
+ pathType: ImplementationSpecific
+ tls:
+ - secretName: promotions-tls
+ hosts:
+ - promotions.example.org
+You will need the externally reachable URL of this service later on in this guide.
Setup notifications from leaf clusters¶
Once the webhook service is exposed over HTTP/S, you need to create alert/provider resources to send notifications to it from leaf clusters. These notifications represent successful promotions for applications running on the leaf clusters.
Successful promotion events are triggered by Flux's notification controller. You create a Provider pointing to the promotion webhook exposed earlier and an Alert targeting the app's HelmRelease:
---
+apiVersion: notification.toolkit.fluxcd.io/v1beta1
+kind: Provider
+metadata:
+ name: promotion-my-app
+spec:
+ address: "https://promotions.example.org/promotion/pipeline-01/my-app/dev"
+ type: generic-hmac
+ secretRef:
+ name: hmac-secret
+In the example above, the generic-hmac Provider is used to ensure notifications originate from authenticated sources. The referenced Secret, should include a token field which holds the HMAC key. The same HMAC key must be specified in the Secret referenced by the .spec.promotion.strategy.secretRef.name field, so that the pipeline controller can verify any incoming notifications. For more information on the generic-hmac Provider, please refer to the notification controller docs.
Note that by default, the promotion webhook endpoint is exposed at /promotion as shown in the example above. However you may use rewrite rules in your ingress configuration to omit it, if desired. For example, if using NGINX ingress controller, you may use the following annotation:
annotations:
+ nginx.ingress.kubernetes.io/rewrite-target: /promotion/$1
+https://promotions.example.org/pipeline-01/my-app/dev. Tip
You may also use the generic webhook provider type that supports HMAC verification to ensure incoming notifications originate from authenticated sources.
The address field's URL path is comprised of 3 components again:
Weave GitOps Enterprise can then parse the incoming URL path to identify the pipeline resource and look up the next environment for the defined promotion action.
An example Alert might look like this:
---
+apiVersion: notification.toolkit.fluxcd.io/v1beta1
+kind: Alert
+spec:
+ eventSeverity: info
+ eventSources:
+ - kind: HelmRelease
+ name: my-app
+ exclusionList:
+ - .*upgrade.*has.*started
+ - .*is.*not.*ready
+ - ^Dependencies.*
+ providerRef:
+ name: promotion-my-app
+Tip
Be sure to create the Provider/Alert tuple on each of the leaf clusters targeted by a pipeline.
Now as soon as the HelmRelease on the first environment defined in the pipeline is bumped (e.g. by Flux discovering a new version in the Helm repository), an event is sent to the promotion webhook which will determine the next action based on the pipeline definition and chosen strategy. The rest of this guide describes how to setup up any of the available strategies depending on your requirements.
Pull request¶
Danger
Creating pull requests requires a personal access token with write access to your git repo. If the secret containing the token is compromised (and you could assume it as a likely scenario), it could in principle allow someone to delete your production applications.
Please make sure you understand the Security section below before taking the steps to enable automated pull requests.
This section covers adding a promotion by pull request (PR) strategy, so that whenever the application defined in a pipeline is upgraded in one of the pipeline's environments, a PR is created that updates the manifest file setting the application version in the next environment.
The dynamic nature of GitOps deployments requires you to assist Weave GitOps a little with information on which repository hosts the manifest files, how to authenticate with the repository and the Git provider API, and which file hosts the version definition for each environment.
Security¶
Environments and Repositories¶
RBAC¶
Assign permissions at the namespace level where possible. Use RoleBindings as opposed to ClusterRoleBindings to give users rights only within a specific namespace.
Avoid providing wildcard permissions when possible, especially to all resources. As Kubernetes is an extensible system, providing wildcard access gives rights not just to all object types that currently exist in the cluster, but also to all object types which are created in the future.
It is also important to note that list and watch access also effectively allow users to read Secret contents.
Policy¶
By following the guidelines above, you can have a safe initial configuration. However, given there are no deny semantics in RBAC, you need to guard future changes.
An RBAC Role or ClusterRole contains rules that represent a set of permissions. Permissions are purely additive (there are no "deny" rules).
You should ensure that attempts to break this contract are blocked and detected. You could achieve it by using Weave GitOps' Policy capabilities. The Policy Agent acts in two complementary modes: - Admission Controller protects from any attempt to create non-compliant RBAC resources that would end granting access to the secret. - Audit helps you identify already existing resources that are out of compliance. For example, roles created before policy agent was introduced as admission controller.
Once you have enabled Policy, the Policy Library gives you a set of good practices policies that will help you keep pipeline secrets secure according to the previous RBAC recommendations. Deploy them as Kustomization based on the following example:
Tip
In case you don't have access to the Policy Library, work with your Weaveworks Technical Account Manager (TAM) or Weaveworks Customer Reliability Engineer (CRE) to help with this step.
apiVersion: source.toolkit.fluxcd.io/v1
+kind: GitRepository
+metadata:
+ name: policy-library
+ namespace: flux-system
+spec:
+ interval: 10m0s
+ url: https://github.com/weaveworks/policy-library.git
+ secretRef:
+ name: policy-library-github-credentials
+---
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+ name: rbac-secrets-good-practices
+ namespace: flux-system
+spec:
+ interval: 1m0s
+ sourceRef:
+ kind: GitRepository
+ name: policy-library
+ path: ./goodpractices/kubernetes/rbac/secrets
+ prune: true
+Warning
Policies typically allow exclusions, to accommodate privileged workloads like Flux. You can manage them via PolicyConfig. For example, in order to allow Flux you could use the following PolicyConfig:
apiVersion: pac.weave.works/v2beta2
+kind: PolicyConfig
+metadata:
+name: allow-flux
+spec:
+match:
+ apps:
+ - kind: Kustomization
+ name: flux-system
+ namespace: flux-system
+config:
+ weave.templates.rbac-prohibit-wildcards-policyrule-resources:
+ parameters:
+ exclude_label_key: "app.kubernetes.io/part-of"
+ exclude_label_value: "flux"
+ weave.templates.rbac-prohibit-wildcards-policyrule-verbs:
+ parameters:
+ exclude_label_key: "app.kubernetes.io/part-of"
+ exclude_label_value: "flux"
+ weave.policies.rbac-prohibit-list-secrets:
+ parameters:
+ exclude_label_key: "app.kubernetes.io/part-of"
+ exclude_label_value: "flux"
+ weave.policies.rbac-prohibit-watch-secrets:
+ parameters:
+ exclude_label_key: "app.kubernetes.io/part-of"
+ exclude_label_value: "flux"
+ weave.policies.rbac-prohibit-wildcard-secrets:
+ parameters:
+ exclude_label_key: "app.kubernetes.io/part-of"
+ exclude_label_value: "flux"
+Remind not allowing users to create RBAC resources without compliance checks. Otherwise, they could create RBAC resources that could escape this runtime control.
In addition to guarding against privilege escalation via RBAC, you should guard against privilege escalation through workloads:
Permission to create workloads (either Pods, or workload resources that manage Pods) in a namespace implicitly grants access to many other resources in that namespace, such as Secrets, ConfigMaps, and PersistentVolumes that can be mounted in Pods
You could do that by creating pipeline namespaces to hold the Pipeline and its Secret, without permission to run workloads. You could enforce the latter one by using the Policy Containers Should Not Run In Namespace from the Policy Library and PolicyConfig as follows:
Tip
Update updates when onboarding a new pipeline. Consider using Weave Gitops self-service capabilities GitOps Templates or GitOpsSets to help you with the task.
apiVersion: pac.weave.works/v2beta2
+kind: PolicyConfig
+metadata:
+ name: reject-workloads-pipeline-namespace
+spec:
+ match:
+ namespaces:
+ - podinfo
+ config:
+ weave.policies.containers-should-not-run-in-namespace:
+ parameters:
+ custom_namespace: "podinfo"
+Service Account¶
To enable the Pipeline Controller to read the secret, we need to grant access via RBAC. The promotion credentials secret needs to be in the same namespace as the Pipeline resource on the management cluster. You should create a RoleBinding for the Pipeline Controller ServiceAccount in the pipeline namespace. For a pipeline in namespace podinfo, it would look like the following:
---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+ name: read-app-promotion-credentials
+ namespace: podinfo # change for the pipeline namespace
+rules:
+ - apiGroups:
+ - ""
+ resourceNames:
+ - "app-promotion-credentials" # change for the secret name holding the pull requests secret
+ resources:
+ - "secrets"
+ verbs:
+ - "get"
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+ name: pipeline-controller-read-app-promotion-credentials
+ namespace: podinfo
+roleRef:
+ apiGroup: rbac.authorization.k8s.io
+ kind: Role
+ name: read-app-promotion-credentials
+subjects:
+ - kind: ServiceAccount
+ name: chart-pipeline-controller # change in case pipeline controller service account has a different name in your context
+ namespace: flux-system
+Verify Security Context¶
Use pipeline promotions security to verify that your environments meets the security context described earlier.
Once deployed you could see how the different resources are being rejected. See those rejections in the Violations UI:
In addition, verify that the Pipeline controller can only get the secret by the following tests:
List access is denied:
$ kubectl get secret -n podinfo --as=system:serviceaccount:flux-system:chart-pipeline-controller
+
+Error from server (Forbidden): secrets is forbidden: User "system:serviceaccount:flux-system:chart-pipeline-controller" cannot list resource "secrets" in API group "" in the namespace "podinfo"
+Get access is allowed:
$ kubectl get secret -n podinfo --as=system:serviceaccount:flux-system:chart-pipeline-controller app-promotion-credentials
+
+NAME TYPE DATA AGE
+app-promotion-credentials Opaque 1 21m
+Tokens¶
Expand to see example
Expand to see example
Expand to see example
For example, if the case of GitHub, use fine-grained tokens to only allow access to the single repo that your configuration manifests exist.
Add markers to app manifests¶
The discovery of the version field is done using deterministic markers in a YAML manifest file. An example HelmRelease manifest with such a marker looks like this:
---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+spec:
+ chart:
+ spec:
+ version: 0.13.7 # {"$promotion": "pipeline-01:my-app:prod"}
+The value of the $promotion field in the comment is comprised of 3 components separated by colons:
Weave GitOps Enterprise will look for this marker whenever it receives an event from the respective HelmRelease of one of the leaf clusters and patch the file with the version denoted in the event (see the section above for instructions on setting up notification events from leaf clusters). Finally, it will create a Git provider PR to update the version of the application for the next environment in the pipeline.
Supported Git Providers¶
The following Git providers are currently support by this promotion strategy:
Select your Git provider via .spec.promotion.strategy.pull-request.type. For example, for gitlab it would look similar to:
promotion:
+ strategy:
+ pull-request:
+ type: gitlab
+ url: "https://gitlab.com/weaveworks/<my-awesome-project.git>"
+ baseBranch: main
+ secretRef:
+ name: gitlab-promotion-credentials
+More info in the spec.
Credentials Secret¶
In the journey of creating a pull request, there are different secrets involved:
Create a Kubernetes secret with the previous data.
Expand to see example
# example to use git over https with basic auth and pat
+$ kubectl create secret generic promotion-credentials \
+--namespace=pipeline-01 \
+--from-literal="username=<bot account name>" \
+--from-literal="password=<token value>" \
+--from-literal="token=<token value>" \
+--from-literal="hmac-key=<hmac-key value>"
+---
+apiVersion: v1
+kind: Secret
+metadata:
+name: promotion-credentials
+namespace: pipeline-01
+data:
+username: ZXhhbXBsZQ==
+password: ZXhhbXBsZS1wYXNzd29yZA==
+token: Z2hwX01IL3RsTFpXTXZMY0FxVWRYY1ZGL0lGbzh0WDdHNjdsZmRxWQ==
+hmac-key: OEIzMTNBNjQ0REU0OEVGODgxMTJCQ0VFNTQ3NkE=
+type: Opaque
+Tip
Define promotion in pipeline resource¶
The field .spec.promotion.strategy.pull-request defines details about the Git repository used for promoting the given app. Set the secretRef.name field to the name of the Secret created in the previous step and the url and branch fields to the Git repository's HTTPS URL and optionally a specific branch (if the branch is not set, it defaults to main). If using the generic-hmac Provider from leaf clusters, also set the .spec.promotion.strategy.secretRef.name to the name of the Secret created previously.
More info in the spec
Notification¶
This section explains how to configure pipelines to work with external CI systems that are responsible for application promotions.
This strategy uses the notification controller running on the management cluster, to forward any notifications received by the promotion webhook, from leaf clusters to external CI systems. This requires to patch the Flux manifests of the management cluster, in order to allow objects of type Pipeline to be used as event sources. An example of a patch applied to enable this is shown below:
---
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+- gotk-components.yaml
+- gotk-sync.yaml
+patches:
+- patch: |
+ - op: add
+ path: /spec/versions/0/schema/openAPIV3Schema/properties/spec/properties/eventSources/items/properties/kind/enum/-
+ value: Pipeline
+ target:
+ kind: CustomResourceDefinition
+ name: alerts.notification.toolkit.fluxcd.io
+You can now create Provider/Alert resources on the management cluster to forward notifications to external systems. For example, the Provider resource shown below is used to invoke a GitHub Actions workflow on a repository:
---
+apiVersion: notification.toolkit.fluxcd.io/v1beta1
+kind: Provider
+metadata:
+ name: promotion-my-app-via-github-actions
+spec:
+ type: githubdispatch
+ address: https://github.com/my-org/my-app-repo
+ secretRef:
+ name: github-credentials
+To use this Provider, add an Alert that uses the pipeline resource defined on the management cluster as an event source. An example of such an Alert is shown below:
---
+apiVersion: notification.toolkit.fluxcd.io/v1beta1
+kind: Alert
+metadata:
+ name: promotion-my-app-via-github-actions
+spec:
+ eventSeverity: info
+ eventSources:
+ - kind: Pipeline
+ name: my-app
+ namespace: my-app-ns
+ providerRef:
+ name: promotion-my-app-via-github-actions
+The notification controller running on the management cluster is now configured to forward any promotion notifications received from leaf clusters. To actually use this strategy from a pipeline, set the promotion field as shown below:
---
+apiVersion: pipelines.weave.works/v1alpha1
+kind: Pipeline
+metadata:
+ name: my-app
+ namespace: my-app-ns
+spec:
+ promotion:
+ notification: {}
+Promotion notifications from leaf clusters should now be forwarded via the notification controller running on the management cluster and should include information about the version of the application being promoted.
Manual promotion¶
The supported strategies mentioned above, do not require any user interaction when handling promotions. However, there is often a need for a human operator to manually approve a promotion to the next environment. To achieve that, set the spec.promotion.manual key to true.
Expand to see example
apiVersion: pipelines.weave.works/v1alpha1
+kind: Pipeline
+metadata:
+name: my-app
+namespace: my-app-ns
+spec:
+promotion:
+ manual: true
+ strategy:
+ pull-request:
+ type: github
+ url: https://github.com/my-org/my-app-repo
+ baseBranch: main
+ secretRef:
+ name: promotion-credentials
+When this key is set and a promotion is detected, Weave GitOps will prompt the user to manually promote the application to the next environment, via the use of a button shown under the next environment.
Configuration¶
Retry Logic¶
By default if a promotion fails, an exponential back-off retry happens and returns with an error only after three retries.
Through Helm values, the retry logic is configurable.
# values.yaml
+promotion:
+ retry:
+ # Initial delay between retries.
+ delay: 2
+ # Maximum delay between retries.
+ maxDelay: 20
+ # Number of attempts.
+ threshold: 3
+The promotion happens through an HTTP endpoint call, that endpoint may has connection timeout limits, that's why the maxDelay option is there. If the calculated delay would exceed this value, it will use that as delay. For example if the delay values would be [2, 4, 8, 16, 32, 64], but maxDelay is set to 15, the list will be [2, 4, 8, 15, 15, 15]. With this option, the promotion will be retried on failure, but the sum of delay values will be only 59 seconds instead of 126 seconds.
Rate Limiting¶
The promotion endpoint can be exposed to the internet (for example github actions), to mitigate DoS attacks, the endpoint has rate limits. By default it's 20 requests per 30 seconds.
Rate limiting can be configured through Helm values:
# values.yaml
+promotion:
+ rateLimit:
+ # Number of requests allowed in set interval.
+ value: 20
+ interval: 30
+import TierLabel from "../../../_components/TierLabel";
Pipeline ENTERPRISE¶
The Pipeline API defines a resource for continuous delivery pipelines.
An example of a fully defined pipeline that creates pull requests for application promotions is shown below.
apiVersion: pipelines.weave.works/v1alpha1
+kind: Pipeline
+metadata:
+ name: podinfo-02
+ namespace: flux-system
+spec:
+ appRef:
+ apiVersion: helm.toolkit.fluxcd.io/v2beta1
+ kind: HelmRelease
+ name: podinfo
+ environments:
+ - name: dev
+ targets:
+ - namespace: podinfo-02-dev
+ clusterRef:
+ kind: GitopsCluster
+ name: dev
+ namespace: flux-system
+ - name: test
+ targets:
+ - namespace: podinfo-02-qa
+ clusterRef:
+ kind: GitopsCluster
+ name: dev
+ namespace: flux-system
+ - namespace: podinfo-02-perf
+ clusterRef:
+ kind: GitopsCluster
+ name: dev
+ namespace: flux-system
+ - name: prod
+ targets:
+ - namespace: podinfo-02-prod
+ clusterRef:
+ kind: GitopsCluster
+ name: prod
+ namespace: flux-system
+ promotion:
+ strategy:
+ pull-request:
+ type: github
+ url: https://github.com/my-org/my-app-repo
+ baseBranch: main
+ secretRef:
+ name: github-credentials
+Specification¶
The documentation for version v1alpha1 of a Pipeline resource is found next.
Pipeline¶
// Pipeline is the Schema for the pipelines API
+type Pipeline struct {
+ metav1.TypeMeta `json:",inline"`
+ metav1.ObjectMeta `json:"metadata,omitempty"`
+
+ Spec PipelineSpec `json:"spec,omitempty"`
+ // +kubebuilder:default={"observedGeneration":-1}
+ Status PipelineStatus `json:"status,omitempty"`
+}
+
+type PipelineSpec struct {
+ // Environments is a list of environments to which the pipeline's application is supposed to be deployed.
+ // +required
+ Environments []Environment `json:"environments"`
+ // AppRef denotes the name and type of the application that's governed by the pipeline.
+ // +required
+ AppRef LocalAppReference `json:"appRef"`
+ // Promotion defines details about how promotions are carried out between the environments
+ // of this pipeline.
+ // +optional
+ Promotion *Promotion `json:"promotion,omitempty"`
+}
+
+type Environment struct {
+ // Name defines the name of this environment. This is commonly something such as "dev" or "prod".
+ // +required
+ Name string `json:"name"`
+ // Targets is a list of targets that are part of this environment. Each environment should have
+ // at least one target.
+ // +required
+ Targets []Target `json:"targets"`
+ // Promotion defines details about how the promotion is done on this environment.
+ // +optional
+ Promotion *Promotion `json:"promotion,omitempty"`
+}
+
+type Target struct {
+ // Namespace denotes the namespace of this target on the referenced cluster. This is where
+ // the app pointed to by the environment's `appRef` is searched.
+ // +required
+ Namespace string `json:"namespace"`
+ // ClusterRef points to the cluster that's targeted by this target. If this field is not set, then the target is assumed
+ // to point to a Namespace on the cluster that the Pipeline resources resides on (i.e. a local target).
+ // +optional
+ ClusterRef *CrossNamespaceClusterReference `json:"clusterRef,omitempty"`
+}
+
+// Promotion define promotion configuration for the pipeline.
+type Promotion struct {
+ // Manual option to allow promotion between to require manual approval before proceeding.
+ // +optional
+ Manual bool `json:"manual,omitempty"`
+ // Strategy defines which strategy the promotion should use.
+ Strategy Strategy `json:"strategy"`
+}
+
+// Strategy defines all the available promotion strategies. All of the fields in here are mutually exclusive, i.e. you can only select one
+// promotion strategy per Pipeline. Failure to do so will result in undefined behaviour.
+type Strategy struct {
+ // PullRequest defines a promotion through a Pull Request.
+ // +optional
+ PullRequest *PullRequestPromotion `json:"pull-request,omitempty"`
+ // Notification defines a promotion where an event is emitted through Flux's notification-controller each time an app is to be promoted.
+ // +optional
+ Notification *NotificationPromotion `json:"notification,omitempty"`
+ // SecrefRef reference the secret that contains a 'hmac-key' field with HMAC key used to authenticate webhook calls.
+ // +optional
+ SecretRef *meta.LocalObjectReference `json:"secretRef,omitempty"`
+}
+type GitProviderType string
+
+const (
+ Github GitProviderType = "github"
+ Gitlab GitProviderType = "gitlab"
+ BitBucketServer GitProviderType = "bitbucket-server"
+)
+
+type PullRequestPromotion struct {
+ // Indicates the git provider type to manage pull requests.
+ // +required
+ // +kubebuilder:validation:Enum=github;gitlab;bitbucket-server
+ Type GitProviderType `json:"type"`
+ // The git repository HTTPS URL used to patch the manifests for promotion.
+ // +required
+ URL string `json:"url"`
+ // The branch to checkout after cloning. Note: This is just the base
+ // branch that will eventually receive the PR changes upon merge and does
+ // not denote the branch used to create a PR from. The latter is generated
+ // automatically and cannot be provided.
+ // +required
+ BaseBranch string `json:"baseBranch"`
+ // SecretRef specifies the Secret containing authentication credentials for
+ // the git repository and for the Git provider API.
+ // For HTTPS repositories the Secret must contain 'username' and 'password'
+ // fields.
+ // For Git Provider API to manage pull requests, it must contain a 'token' field.
+ // +required
+ SecretRef meta.LocalObjectReference `json:"secretRef"`
+}
+
+type NotificationPromotion struct{}
+References¶
// LocalAppReference is used together with a Target to find a single instance of an application on a certain cluster.
+type LocalAppReference struct {
+ // API version of the referent.
+ // +required
+ APIVersion string `json:"apiVersion"`
+
+ // Kind of the referent.
+ // +required
+ Kind string `json:"kind"`
+
+ // Name of the referent.
+ // +required
+ Name string `json:"name"`
+}
+
+// CrossNamespaceClusterReference contains enough information to let you locate the
+// typed Kubernetes resource object at cluster level.
+type CrossNamespaceClusterReference struct {
+ // API version of the referent.
+ // +optional
+ APIVersion string `json:"apiVersion,omitempty"`
+
+ // Kind of the referent.
+ // +required
+ Kind string `json:"kind"`
+
+ // Name of the referent.
+ // +required
+ Name string `json:"name"`
+
+ // Namespace of the referent, defaults to the namespace of the Kubernetes resource object that contains the reference.
+ // +optional
+ Namespace string `json:"namespace,omitempty"`
+}
+Status¶
type PipelineStatus struct {
+ // ObservedGeneration is the last observed generation.
+ // +optional
+ ObservedGeneration int64 `json:"observedGeneration,omitempty"`
+
+ // Conditions holds the conditions for the Pipeline.
+ // +optional
+ Conditions []metav1.Condition `json:"conditions,omitempty"`
+}
+Condition Reasons¶
// Reasons are provided as utility, and are not part of the declarative API.
+const (
+ // TargetClusterNotFoundReason signals a failure to locate a cluster resource on the management cluster.
+ TargetClusterNotFoundReason string = "TargetClusterNotFound"
+ // TargetClusterNotReadyReason signals that a cluster pointed to by a Pipeline is not ready.
+ TargetClusterNotReadyReason string = "TargetClusterNotReady"
+ // ReconciliationSucceededReason signals that a Pipeline has been successfully reconciled.
+ ReconciliationSucceededReason string = "ReconciliationSucceeded"
+)
+Authorization ENTERPRISE¶
This section provides a recommended way to configure RBAC in the context of policies. It is oriented to the journey that you expect your users to have.
View Resources¶
The policy journey in the UI involves several resources. We have the Policies that are used by the agent, the resulting Violations when the agent enforces those policies, and the PolicyConfigs that the user can configure to override policy parameters. The violations are essentially kubernetes events that contain the Validation object.
In order to view those resources, users would need to have read access to the policies, policysconfigs, and events resource.
An example of a configuration to achieve this purpose could be seen below with policies-reader role and developer-policies-reader cluster role binding, to allow a group developer to access all the policy-related resources.
apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+ name: policies-reader
+rules:
+ - apiGroups: ["pac.weave.works"]
+ resources: ["policies", "policyconfigs"]
+ verbs: ["get", "list", "watch"]
+ - apiGroups: [""]
+ resources: ["events"]
+ verbs: ["get", "watch", "list"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+ name: developer-policies-reader
+subjects:
+ - kind: Group
+ name: developer
+ apiGroup: rbac.authorization.k8s.io
+roleRef:
+ kind: ClusterRole
+ name: policies-reader
+ apiGroup: rbac.authorization.k8s.io
+Commit/Build Time Checks ENTERPRISE¶
Overview¶
Weave GitOps Enterprise enables developers and operators to check policy violations early in their software development life cycle, specifically at commit and build time. Developers and operators can have Weave Policy Validator integrated in their CI tools to validate whether their code changes are violating any policies or not.
Weave GitOps Enterprise offer a policy engine image that can be used to perform commit/build time checks.The image can be found on Docker Hub under the name: weaveworks/weave-iac-validator:v1.1.
Expand to view of the usage options
USAGE:
+ app [global options] command [command options] [arguments...]
+
+VERSION:
+ 0.0.1
+
+COMMANDS:
+ help, h Shows a list of commands or help for one command
+
+GLOBAL OPTIONS:
+ --path value path to scan resources from
+ --helm-values-file value path to resources helm values file
+ --policies-path value path to policies kustomization directory
+ --policies-helm-values-file value path to policies helm values file
+ --git-repo-provider value git repository provider
+ --git-repo-host value git repository host
+ --git-repo-url value git repository url
+ --git-repo-branch value git repository branch
+ --git-repo-sha value git repository commit sha
+ --git-repo-token value git repository toke
+ --azure-project value azure project name
+ --sast value save result as gitlab sast format
+ --sarif value save result as sarif format
+ --json value save result as json format
+ --generate-git-report generate git report if supported (default: false)
+ --remediate auto remediate resources if possible (default: false)
+ --no-exit-error exit with no error (default: false)
+ --help, -h show help (default: false)
+ --version, -v print the version (default: false)
+Setup policies¶
Policies can be a helm chart, kustomize directory or just plain kubernetes yaml files.
Example of policies kustomize directory
└── policies
+ ├── kustomization.yaml
+ ├── minimum-replica-count.yaml
+ ├── privileged-mode.yaml
+ └── privilege-escalation.yaml
+ # kustomization.yaml
+ kind: Kustomization
+ apiVersion: kustomize.config.k8s.io/v1beta1
+ resources:
+ - minimum-replica-count.yaml
+ - privilege-escalation.yaml
+ - privileged-mode.yaml
+Supported CI/CD¶
Auto-Remediation¶
Weave validator supports auto-remediation functionality which creates a pull request with suggested fixes to remediate the reported violations.
Supported in:
To enable it you need to provide --remediate flag and --git-repo-token.
The token must have the permission to create a pull request.
UseCase: Github¶
See how to setup the Github Action
UseCase: Gitlab¶
weave:
+ image:
+ name: weaveworks/weave-iac-validator:v1.1
+ script:
+ - weave-validator --path <path to resources> --policies-path <path to policies>
+Enable Auto Remediation¶
script:
+ - weave-validator --path <path to resources> --policies-path <path to policies> --git-repo-token $GITLAB_TOKEN --remediate
+Enable Static Application Security Testing¶
stages:
+ - weave
+ - sast
+
+ weave:
+ stage: weave
+ image:
+ name: weaveworks/weave-iac-validator:v1.1
+ script:
+ - weave-validator <path to resources> --policies-path <path to policies> --sast sast.json
+ artifacts:
+ when: on_failure
+ paths:
+ - sast.json
+
+ upload_sast:
+ stage: sast
+ when: always
+ script:
+ - echo "creating sast report"
+ artifacts:
+ reports:
+ sast: sast.json
+UseCase: Bitbucket¶
pipelines:
+ default:
+ - step:
+ name: 'Weaveworks'
+ image: weaveworks/weave-iac-validator:v1.1
+ script:
+ - weave-validator --path <path to resources> --policies-path <path to policies>
+Enable Auto Remediation¶
script:
+ - weave-validator --path <path to resources> --policies-path <path to policies> --git-repo-token $TOKEN --remediate
+Create Pipeline Report¶
script:
+ - weave-validator --path <path to resources> --policies-path <path to policies> --git-repo-token $TOKEN -generate-git-report
+UseCase: CircleCI¶
jobs:
+ weave:
+ docker:
+ - image: weaveworks/weave-iac-validator:v1.1
+ steps:
+ - checkout
+ - run:
+ command: weave-validator --path <path to resources> --policies-path <path to policies>
+Enable Auto Remediation¶
- run:
+ command: weave-validator --path <path to resources> --policies-path <path to policies> --git-repo-token ${GITHUB_TOKEN} --remediate
+UseCase: Azure DevOps¶
trigger:
+- <list of branches to trigger the pipeline on>
+
+pool:
+ vmImage: ubuntu-latest
+
+container:
+ image: weaveworks/weave-iac-validator:v1.1-azure
+
+steps:
+- script: weave-validator --path <path to resources> --policies-path <path to policies> --git-repo-token $(TOKEN)
+Enable Auto Remediation¶
steps:
+- script: weave-validator --path <path to resources> --policies-path <path to policies> --git-repo-token $(TOKEN) --remediate
+Getting Started ENTERPRISE¶
Enabling the Weave Policy Engine features in Weave GitOps is done by running the policy agent on the cluster. This section gives an overview of the policy ecosystem and the steps required for installing and running the policy agent on leaf clusters.
The Policy Ecosystem¶
The policy ecosystem consists of several moving parts. The two primary components are the Policy Agent and the Policy CRs. The agent runs in several modes, and uses the Policy CRs to perform validations on different resources. The results of those validations can be written to different sinks.
There are two other optional components: the PolicySet, and the PolicyConfig. The PolicySet can be used to filter policies for a specific mode, while the PolicyConfig can be used to override policy parameters during the validation of a certain resource.
Installation Pre-requisites¶
Weave GitOps¶
You need to have a running instance of Weave GitOps with at least one CAPI provider installed to provision Kubernetes clusters. See Weave GitOps Installation page for more details about installing Weave GitOps.
Policy Library¶
For the policy agent to work, it will need a source for the policies that it will enforce in the cluster. Enterprise customers should request access to fork our policy library into their local repositories. Our policy library includes an extensive list of policy CRs that cover a multitude of security and compliance benchmarks.
Install the Policy Agent¶
To install the policy agent on a leaf cluster, you should select the weave-policy-agent from the profiles dropdown in the Create Cluster page.
You should then configure the values.yaml to pull the policies from your repo into the cluster. This is done by configuring the policySource section. If your policy library repo is private, you will also need to reference the Secret that contains the repo credentials. This is usually the secret you created while bootstrapping Flux on the management cluster and is copied to your leaf cluster during creation.
Expand to see an example that creates a new git source
policySource:
+enabled: true
+url: ssh://git@github.com/weaveworks/policy-library # This should be the url of the forked repo
+tag: v1.0.0
+path: ./ # Could be a path to the policies dir or a kustomization.yaml file
+secretRef: my-pat # the name of the secret containing the repo credentials
+Expand to see an example that uses an existing git source
policySource:
+enabled: true
+sourceRef: # Specify the name for an existing GitSource reference
+ kind: GitRepository
+ name: policy-library
+ namespace: flux-system
+You can find more about other policy profile configurations here.
Policies in UI¶
After the leaf cluster is provisioned and the profile is installed, you should now see the policies listed in the Policies tab in Weave GitOps UI.
Now you have a provisioned cluster with these policies enforced by the policy agent.
By default, the policy profile is set up to enforce policies at deployment time using admission controller, which results in blocking any deployment that violates the enforced policies.
Prevent Violating Changes¶
Now let's try to deploy a Kubernetes deployment that violates the Container Image Pull Policy which is one of the enforced policies. This policy is violated when the container's imagePullPolicy is not set to Always.
Expand for an example of a violating deployment
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
+ imagePullPolicy: IfNotPresent
+ ports:
+ - containerPort: 80
+Once you apply it, the policy agent will deny this request and show a violation message, and accordingly the deployment will not be created.
Violations Logs in UI¶
You can go to the Violations Log in Weave GitOps UI to view the policy violations of all the connected clusters, and dive into the details of each violation.
This view shows only the violations resulting from the admission mode by configuring the events sink.
Violations Log
Violations Log Details
Introduction ENTERPRISE¶
Policy¶
Weave Policy Engine helps users have continuous security and compliance checks across their software delivery pipeline. The engine utilizes policy-as-code to guarantee security, resilience, and coding standards across applications and infrastructure. The engine comes with 100+ policies covering numerous security and compliance benchmarks like SOC2, GDPR, PCI-DSS, HIPAA, Mitre Attack and more.
The policy engine provides the following functionality:
Admission Controller¶
An out-of-the-box admission controller that monitors any changes happening to the clusters' deployments and resources, and prevents violating changes at deployment time from being deployed to clusters.
Audit¶
Daily scans of your clusters' deployments and resources, then report back any policy violations. The audit results can be published to different data analytics tools to provide compliance posture analysis of your clusters runtime.
Commit/Build Time Checks¶
Early feedback on policy violations at the commit or build time, by reporting policy violations right inside git or other CI tools. This helps developers and operators detect policy violations and fix them before they deploy their changes to the clusters.
PolicyConfig ENTERPRISE¶
Goal¶
Users sometimes need to enforce the same policy(s) with different configurations (parameters) for different targets (workspaces, namespaces, applications, or resources). The PolicyConfig CRD allows us to do that without duplicating policies by overriding policy parameters of multiple policies for a specific target.
Schema¶
The PolicyConfig CRD consists of two sections 1) match used to specify the target of this PolicyConfig and 2) config used to specify the policy parameters that will override the orginal policy parameters.
Expand to see a PolicyConfig example
apiVersion: pac.weave.works/v2beta2
+kind: PolicyConfig # policy config resource kind
+metadata:
+name: my-config # policy config name
+spec:
+match: # matches (targets of the policy config)
+ workspaces: # add one or more name workspaces
+ - team-a
+ - team-b
+config: # config for policies [one or more]
+ weave.policies.containers-minimum-replica-count:
+ parameters:
+ replica_count: 3
+Each PolicyConfig CR can target either workspaces, namespaces, applications or resources. Targeting the same target explicitly in multiple PolicyConfigs is not allowed, ie: you can't use the same namespace in several PolicyConfigs which target namespaces.
To target workspaces:
match:
+ workspaces:
+ - team-a
+ - team-b
+To target namespaces:
match:
+ namespaces:
+ - dev
+ - prod
+To target applications:
match:
+ apps: # add one or more apps [HelmRelease, Kustomization]
+ - kind: HelmRelease
+ name: my-app # app name
+ namespace: flux-system # app namespace [if empty will match in any namespace]
+To target resources:
match:
+ resources: # add one or more resources [Deployment, ReplicaSet, ..]
+ - kind: Deployment
+ name: my-deployment # resource name
+ namespace: default # resource namespace [if empty will match in any namespace]
+Each PolicyConfig can override the parameters of one or more policies:
config: # config for policies [one or more]
+ weave.policies.containers-minimum-replica-count: # the id of the policy
+ parameters:
+ replica_count: 3
+ owner: owner-4
+ weave.policies.containers-running-in-privileged-mode:
+ parameters:
+ privilege: true
+Overlapping Targets¶
While it's not possible to create PolicyConfigs that explicitly target the same targets, it can happen implicitly ex: by targeting a namespace in a PolicyConfig and targeting an application that exists in this namespace in another. Whenever targets overlap, the narrower the scope of the PolicyConfig, the more precedence it has. Accordingly in the previous example, the configuration of the PolicyConfig targeting the application will have precedence over the PolicyConfig targeting the namespace.
Those are the possible targets from lowest to highest precedence:
Note:
Example¶
We have a Kustomization application app-a and deployment deployment-1 which is part of this application.
Expand to see manifests
apiVersion: pac.weave.works/v2beta2
+kind: PolicyConfig
+metadata:
+name: my-config-1
+spec:
+match:
+ namespaces:
+ - flux-system
+config:
+ weave.policies.containers-minimum-replica-count:
+ parameters:
+ replica_count: 2
+ owner: owner-1
+---
+apiVersion: pac.weave.works/v2beta2
+kind: PolicyConfig
+metadata:
+name: my-config-2
+spec:
+match:
+ apps:
+ - kind: Kustomization
+ name: app-a
+config:
+ weave.policies.containers-minimum-replica-count:
+ parameters:
+ replica_count: 3
+---
+apiVersion: pac.weave.works/v2beta2
+kind: PolicyConfig
+metadata:
+name: my-config-3
+spec:
+match:
+ apps:
+ - kind: Kustomization
+ name: app-a
+ namespace: flux-system
+config:
+ weave.policies.containers-minimum-replica-count:
+ parameters:
+ replica_count: 4
+---
+apiVersion: pac.weave.works/v2beta2
+kind: PolicyConfig
+metadata:
+name: my-config-4
+spec:
+match:
+ resources:
+ - kind: Deployment
+ name: deployment-1
+config:
+ weave.policies.containers-minimum-replica-count:
+ parameters:
+ replica_count: 5
+ owner: owner-4
+---
+
+apiVersion: pac.weave.works/v2beta2
+kind: PolicyConfig
+metadata:
+name: my-config-5
+spec:
+match:
+ resources:
+ - kind: Deployment
+ name: deployment-1
+ namespace: flux-system
+config:
+ weave.policies.containers-minimum-replica-count:
+ parameters:
+ replica_count: 6
+In the above example when you apply the 5 configurations...
Note
Deploying deployment-1 in another namespace other than flux-system won't be affected by this configuration
Final config values will be as follows:
config:
+ weave.policies.containers-minimum-replica-count:
+ parameters:
+ replica_count: 6 # from my-config-5
+ owner: owner-4 # from my-config-4
+In the above example when you apply my-config-1, my-config-2, my-config-3 and my-config-4
Final config values will be as follows:
config:
+ weave.policies.containers-minimum-replica-count:
+ parameters:
+ replica_count: 5 # from my-config-4
+ owner: owner-4 # from my-config-4
+In the previous example when you apply my-config-1, my-config-2 and my-config-3
Note
Deploying app-a in another namespace other than flux-system won't be affected by this configuration
Final config values will be the follows:
config:
+ weave.policies.containers-minimum-replica-count:
+ parameters:
+ replica_count: 4 # from my-config-3
+ owner: owner-1 # from my-config-1
+In the above example when you apply my-config-1 and my-config-2
Final config values will be as follows:
config:
+ weave.policies.containers-minimum-replica-count:
+ parameters:
+ replica_count: 3 # from my-config-2
+ owner: owner-1 # from my-config-1
+In the above example when you apply my-config-1
Final config values will be as follows:
config:
+ weave.policies.containers-minimum-replica-count:
+ parameters:
+ replica_count: 2 # from my-config-1
+ owner: owner-1 # from my-config-1
+PolicySet ENTERPRISE¶
This is an optional custom resource that is used to select a group of policies to work in specific modes.
In each mode, the agent will list all the PolicySets of this mode and check which policies match any of those policysets, then validate the resources against them.
If there are no PolicySets found for a certain mode, all policies will be applied during this mode.
Note: Tenant Policies is always active in the Admission mode, event if it is not selected in the
admissionpolicysets
Example
apiVersion: pac.weave.works/v2beta2
+kind: PolicySet
+metadata:
+ name: my-policy-set
+spec:
+ mode: admission
+ filters:
+ ids:
+ - weave.policies.containers-minimum-replica-count
+ categories:
+ - security
+ severities:
+ - high
+ - medium
+ standards:
+ - pci-dss
+ tags:
+ - tag-1
+PolicySets can be created for any of the three modes supported by the agent: admission, audit, and tfAdmission.
Grouping Policies¶
Policies can be grouped by their ids, categories, severities, standards and tags
The policy will be applied if any of the filters are matched.
Migration from v2beta1 to v2beta2¶
New fields¶
Previously the agent was configured with which policysets to use in each mode. Now we removed this argument from the agent's configuration and add the mode to the Policyset itself.
Example of the agent configuration in versions older than v2.0.0¶
# config.yaml
+admission:
+ enabled: true
+ policySet: admission-policy-set
+ sinks:
+ filesystemSink:
+ fileName: admission.txt
+Example of current PolicySet with mode field¶
apiVersion: pac.weave.works/v2beta2
+kind: PolicySet
+metadata:
+ name: admission-policy-set
+spec:
+ mode: admission
+ filters:
+ ids:
+ - weave.policies.containers-minimum-replica-count
+Updated fields¶
Deprecate fields¶
Policy ENTERPRISE¶
Policy CRD¶
The Policy CRD is used to define policies which are then consumed and used by the agent to validate entities.
It uses OPA Rego Language to evaluate the entities.
Policy Library¶
You should have a policy library repo set up which includes your policies resources as CRDs.
Info
Enterprise customers should have access to fork policy library repo into their local repositories.
Tenant Policy¶
Tenant policies are special policies that are used by the Multi Tenancy feature in Weave GitOps Enterprise
Tenant policies have a special tag tenancy.
Mutating Resources¶
Starting from version v2.2.0, the policy agent will support mutating resources.
To enable mutating resources, policies must have field mutate set to true and the rego code should return the violating_key and the recommended_value in the violation response. The mutation webhook will use the violating_key and recommended_value to mutate the resource and return the new mutated resource.
Example
result = {
+ "issue_detected": true,
+ "msg": sprintf("Replica count must be greater than or equal to '%v'; found '%v'.", [min_replica_count, replicas]),
+ "violating_key": "spec.replicas",
+ "recommended_value": min_replica_count
+}
+Policy Validation¶
The policy validation object is the result of validating an entity against a policy. It contains all the necessary information to give the user a clear idea on what caused this violation or compliance.
id: string # identifier for the violation
+account_id: string # organization identifier
+cluster_id: string # cluster identifier
+policy: object # contains related policy data
+entity: object # contains related resource data
+status: string # Violation or Compliance
+message: string # message that summarizes the policy validation
+type: string # the mode that produced this object. one of: Admission, Audit, TFAdmission
+trigger: string # what triggered the validation, create request or initial audit,..
+created_at: string # time that the validation occurred in
+Profile Releases ENTERPRISE¶
v0.6.5¶
Highlights¶
Dependency Versions¶
Policy Library Compatibility¶
Compatible with Policy Library versions:
Needs this migration steps to be compatible with the following versions:
v0.6.4¶
Highlights¶
Dependency Versions¶
Policy Library Compatibility¶
Compatible with Policy Library versions:
Needs this migration steps to be compatible with the following versions:
v0.6.3¶
Highlights¶
Dependency Versions¶
Policy Library Compatibility¶
v0.6.2¶
Highlights¶
Dependency Versions¶
Policy Library Compatibility¶
While both v.0.4.0 and v1.0.0 are compatible with the agent. Only v1.1.0 includes the modification needed to make Controller Minimum Replica Count policy with with horizontalpodautoscalers
v0.6.1¶
Highlights¶
Dependency Versions¶
Policy Library Compatibility¶
v0.6.0¶
Highlights¶
Dependency Versions¶
Policy Library Compatibility¶
Policy Profile ENTERPRISE¶
Overview¶
Weave policy profile provides policies to automate the enforcement of best practices and conventions. It ensures the compliance of workloads through the use of a policy agent that provides an admission controller webhook that stops violating resources from deploying to a cluster and runs a daily audit that reports violating resources already deployed.
The profile configuration contains two main sections policySource to configure the source for deploying policies and policy-agent to configure the policy agent.
Expand for an example of the profile values file
policy-agent:
+failurePolicy: Ignore
+
+# If you don't want to use cert-manager, set useCertManager to false and provide your own certs
+useCertManager: true
+certificate: ""
+key: ""
+caCertificate: ""
+
+persistence:
+ enabled: false
+ # claimStorage: 1Gi
+ # sinkDir: /tmp
+ # storageClassName: standard
+
+config:
+ accountId: ""
+ clusterId: ""
+
+ audit:
+ # Enable audit functionality
+ enabled: false
+ # sinks:
+ # # Enable writing violations as K8s events
+ # k8sEventsSink:
+ # enabled: true
+
+ admission:
+ # Enable admission functionality
+ enabled: true
+ # mutate: true # enable mutating violating resources
+ sinks:
+ # Enable writing violations as K8s events
+ k8sEventsSink:
+ enabled: true
+
+
+policySource:
+enabled: false
+# url: ssh://git@github.com/weaveworks/policy-library
+# tag: v1.0.0
+# branch:
+# path: ./ # Could be a path to the policies dir or a kustomization.yaml file
+# secretRef: policy-library-auth # (Optional): Name of the K8s secret with private repo auth credentials
+# sourceRef: # Could specify a name for an existing GitSource reference instead of creating a new one
+# kind: GitRepository
+# name: policy-library
+# namespace: flux-system
+Policy Sources¶
Policies are provided in the profile as Custom Resources. The agent reads from the policies deployed on the cluster and runs them during each admission request or when auditing a resource.
Policies are hosted in a policy library which is usually a git repository. They are fetched in the profile through the use of kustomize.toolkit.fluxcd.io.Kustomization, that deploys the policies to the cluster.
By default all policies in the specified path would be deployed in order to specify which policies should be deployed in a library, a kustomize.config.k8s.io.Kustomization file should be defined in the repository.
apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources: # specifies the path to each required policy
+ - policies/ControllerContainerAllowingPrivilegeEscalation/policy.yaml
+ - policies/ControllerContainerRunningAsRoot/policy.yaml
+ - policies/ControllerReadOnlyFileSystem/policy.yaml
+The profile then needs to be configured with the necessary config to be able to reach the repository that is acting as a policy library.
policySource:
+ enabled: true
+ url: URL of the repo where your policies exist
+ tag: tag name on the policies repo
+ path: Path to the policies dir - or a kustomization.yaml that selects some policies - in the repo
+ secretRef (if the repo is private): Name of the K8s secret with private repo credentials (leave empty if the repo is public)
+There is the option of referencing an existing policy library source instead of creating a new one.
policySource:
+ enabled: true
+ sourceRef:
+ kind: Kind of the existing source
+ name: Name of the policy library source
+ namespace: Namespace where the source exists
+Policy Agent Configuration¶
The config section is the single entry point for configuring the agent.
The agent needs the following parameters to be provided in the configuration yaml file:
The following optional parameters can also be provided:
Agent Modes¶
Admission¶
This contains the admission module that enforces policies. It uses the controller-runtime Kubernetes package to register a callback that will be called when the agent receives an admission request. Once called, the agent will validate the received resource against the admission and tenant policies and k8s will use the result of this validation to either allow or reject the creation/update of said resource.
Works with policies of provider
kubernetes
To enable admission control:
policy-agent:
+ config:
+ admission:
+ enabled: true
+Enabling admission controller requires certificates for secure communication with the webhook client and the admission server. The best way to achieve this is by installing cert manager and then configuring the profile as follows:
policy-agent:
+ useCertManager: true
+The cert manager can also be installed by installing the cert manager profile while creating the cluster.
There is the option of providing previously generated certificates although it is not recommended and it is up to the user to manage it:
policy-agent:
+ certificate: "---" # admission server certificate
+ key: "---" # admission server private key
+ caCertificate: "---" # CA bundle to validate the webhook server, used by the client
+If the agent webhook could not be reached or the request failed to complete, the corresponding request would be refused. To change that behavior and accepts the request in cases of failure, this needs to be set:
policy-agent:
+ failurePolicy: Ignore
+Audit¶
The audit functionality provides a full scan of the cluster(s) and reports back policy violations. This usually is used for policy violations reporting, and compliance posture analysis against known benchmarks like PCI DSS, CIS, .etc.
Works with policies of provider
kubernetes
To enable the audit functionality:
policy-agent:
+ config:
+ audit:
+ enabled: true
+ interval: 24 # configuring the frequent of audit operations running in hours (default is 24 hours)
+The audit will be performed when the agent starts and then again periodically at an interval of your choice in hours (default is 24 hours). The results of the audit will be published to the configured sink(s).
Terraform Admission¶
This is a webhook used to validate terraform plans. It is mainly used by the TF-Controller to enforce policies on terraform plans
Works with policies of provider
terraform
To enable the terraform admission control:
policy-agent:
+ config:
+ tfAdmission:
+ enabled: true
+Policy Validation Sinks¶
When validating a resource, a validation object is generated that contains information about the status of that validation and metadata about the resource and policy involved. These objects can be exported to be visible for users as a critical part of the audit flow, but can also be useful as logs for the admission scenario.
By default, the agent only writes policy validations that are violating a certain policy when performing an audit. To write compliance results as well, the following needs to be specified in the profile:
policy-agent:
+ config:
+ audit:
+ writeCompliance: true
+The agent profile supports storing the validations in different sinks. Multiple sinks can be used at the same time:
The results will be dumped into a text file in the logs directory, in the agent container as a json string. It is important to note that this file will not be persisted and will be deleted upon pod restart, so generally this approach is not recommended for a production environment.
To enable writing to a text file in audit scenario:
policy-agent:
+config:
+ audit:
+ sinks:
+ fileSystemSink:
+ fileName: "file.json"
+To enable writing to a text file in admission scenario:
policy-agent:
+config:
+ admission:
+ sinks:
+ fileSystemSink:
+ fileName: "file.json"
+It is possible to make the file persistent using the following configuration. This assumes that there is a PersistentVolume already configured on the cluster.
policy-agent:
+persistence:
+ enabled: false # specifies whether to use persistence or not
+ claimStorage: 1Gi # claim size
+ storageClassName: standard # k8s StorageClass name
+The results will be written as Kubernetes events. This means that they are accessible through the kubernetes API and can be consumed by custom exporters.
To enable writing Kubernetes events in audit scenario:
policy-agent:
+config:
+ audit:
+ sinks:
+ k8sEventsSink:
+ enabled: true
+To enable writing Kubernetes events in admission scenario:
policy-agent:
+config:
+ admission:
+ sinks:
+ k8sEventsSink:
+ enabled: true
+This requires the cluster to be managed using flux. It makes use of the flux notification controller to send events to multiple sources, depending on the controller configuration. The agent writes the events to the controller and it proceeds to publish it to the configured listeners.
To enable writing to flux notification controller in audit scenario:
policy-agent:
+config:
+ audit:
+ sinks:
+ fluxNotificationSink:
+ address: ""
+To enable writing to flux notification controller in admission scenario:
policy-agent:
+config:
+ admission:
+ sinks:
+ fluxNotificationSink:
+ address: ""
+The results of validating entities against policies will be written to an Elasticsearch index.
To enable writing to elasticsearch in audit scenario:
policy-agent:
+config:
+ audit:
+ sinks:
+ elasticSink:
+ address: ""
+ username: ""
+ password: ""
+ indexName: ""
+ insertionMode: "upsert"
+To enable writing to elasticsearch in admission scenario:
policy-agent:
+config:
+ admission:
+ sinks:
+ elasticSink:
+ address: ""
+ username: ""
+ password: ""
+ indexName: ""
+ insertionMode: "insert"
+We support the following insertion modes:
Manual Approval for Progressive Delivery Deployments ENTERPRISE¶
To help you understand the state of progressive delivery updates to your applications, Weave GitOps Enterprise uses Flagger—part of the Flux family of open source projects. WGE's Delivery view shows all of your deployed Canary objects and rollout progress.
By default, Flagger automatically promotes a new version of an application whenever it passes the defined checks of an analysis phase. However, you can also configure webhooks to enable manual approvals of rollout stages.
This guide shows you how to manually gate a progressive delivery promotion with Flagger by using the in-built load tester.
Prerequisites¶
Basic Introduction to Webhooks and Gating¶
You can configure Flagger to work with several types of hooks that will be called at given stages during a progressive delivery rollout. Some of these hooks allow you to manually gate whether a rollout proceeds at certain points: - Before scaling up a new deployment and canary analysis begins with confirm-rollout. - Before increasing traffic weight with confirm-traffic-increase. - Before promoting a new version after successful canary analysis with confirm-promotion.
Any URL can serve as a webhook target. It will approve if a 200 OK status code is returned, and halt if 403 Forbidden.
The webhook will receive a JSON payload that can be unmarshaled as CanaryWebhookPayload:
type CanaryWebhookPayload struct {
+ // Name of the canary
+ Name string `json:"name"`
+
+ // Namespace of the canary
+ Namespace string `json:"namespace"`
+
+ // Phase of the canary analysis
+ Phase CanaryPhase `json:"phase"`
+
+ // Metadata (key-value pairs) for this webhook
+ Metadata map[string]string `json:"metadata,omitempty"`
+}
+The Flagger documentation provides more information about webhooks.
Use Flagger's Load Tester to Manually Gate a Promotion¶
To enable manual approval of a promotion, configure the confirm-promotion webhook. This will call a particular gate provided through Flagger's load tester, and is an easy way to experiment using Flagger's included components.
Tip
We strongly recommend that you DO NOT USE the load tester for manual gating in a production environment. It lacks auth, so anyone with cluster access could open and close it. It also lacks storage, so all gates would close upon a restart. Instead, configure these webhooks for appropriate integration with a tool of your choice, such Jira, Slack, Jenkins, etc.
Configure the confirm-promotion Webhook¶
In your canary object, add the following in the analysis section:
analysis:
+ webhooks:
+ - name: "ask for confirmation"
+ type: confirm-promotion
+ url: http://flagger-loadtester.test/gate/check
+This gate is closed by default.
Deploy a New Version of Your Application¶
Trigger a Canary rollout by updating your target deployment/daemonset—for example, by bumping the container image tag. A full list of ways to trigger a rollout is available here.
Weave GitOps Enterprise (WGE)'s Applications > Delivery view enables you to watch the progression of a canary:
Wait for the Canary Analysis to Complete¶
Once the canary analysis has successfully completed, Flagger will call the confirm-promotion webhook and change status to WaitingPromotion:
Open the Gate¶
To open the gate and confirm that you approve promotion of the new version of your application, exec into the load tester container:
$ kubectl -n test exec -it flagger-loadtester-xxxx-xxxx sh
+
+# to open
+> curl -d '{"name": "app","namespace":"test"}' http://localhost:8080/gate/open
+Flagger will now promote the canary version to the primary and complete the progressive delivery rollout. 
To manually close the gate again, issue this command:
> curl -d '{"name": "app","namespace":"test"}' http://localhost:8080/gate/close
+References:
Progressive Delivery Using Flagger ENTERPRISE¶
Built upon the core tenets of continuous integration and continuous delivery (CI/CD), progressive delivery involves gradually rolling out features to small groups of select users to balance performance with speed. Developers and DevOps teams use fine-grained controls to minimize the risks of pushing new features to the production environment. If the newly released feature proves to be stable and performant, it can then be released to all users.
Flagger is a progressive delivery operator for Kubernetes and part of the Flux family of open source projects. It reduces the risk of introducing new software versions and automates production releases to improve your time to delivery. Flagger implements deployment strategies—canary releases, A/B testing, Blue/Green mirroring—using a service mesh (App Mesh, Istio, Linkerd, Kuma, Open Service Mesh) or an ingress controller (Contour, Gloo, NGINX, Skipper, Traefik, APISIX) for traffic routing. For release analysis, Flagger can query Prometheus, InfluxDB, Datadog, New Relic, CloudWatch, Stackdriver, or Graphite. For alerting it uses Slack, MS Teams, Discord, and Rocket. Using Flux allows us to manage our cluster applications in a declarative way through changes in a Git repository.
Weave GitOps Enterprise integrates with Flagger in order to provide a view on progressive delivery deployments. This includes the ability to view all the resources that Flagger manages during its operation. The default ClusterRole gitops-canaries-reader includes the minimum permissions necessary for a user to be able to view canary object details, metric template object details and canary related events.
The WGE UI's Applications > Delivery view provides an "at a glance" view so that you can understand the status of your progressive delivery rollouts across a fleet of connected clusters. This removes the cognitive overhead of having to know which objects to query and where they are located. You can also drill down into each rollout to understand its status and configuration, and view near-to-realtime data on any summary or details page.
How to use WGE's progressive delivery offering: - if you don’t have Flagger installed on any clusters, you'll receive an onboarding message about installing it - click on the delivery tab on the menu bar to retrieve a table view of canaries with key summary information regarding their location and state - click on a canary to see more detailed information about status, gates, and other elements - click on the events tab on the detail page to see the most recent Kubernetes events for that canary and learn more about deployment history - click on the yaml tab on the detail page to see the raw yaml of the canary - view objects from any cluster/namespace that you have the appropriate permissions for, and nothing else
Supported deployment strategies include:
Canary Release: the system gradually shifts traffic to a new version of an application and assesses performance—either promoting the release or abandoning it, based on performance.
A/B Testing: uses HTTP headers or cookies to ensure users remain on the same version of an application during a canary analysis.
Blue/Green: Traffic is switched from the current application to a new version based on the success of testing.
Blue/Green with Traffic Mirroring: sends copies of incoming requests to the new version of an application. The user receives the response from the current application and the other is discarded. The new version is promoted only if metrics are healthy.
This guide uses Flux manifests to install Flagger and Linkerd, a CNCF project and service mesh for Kubernetes and beyond. We will walk you through a full end-to-end scenario where you will: - Install the Linkerd service mesh - Install Flagger - Deploy a sample application using a canary release strategy based on metrics provided through Linkerd's in-built Prometheus instance
Prerequisites¶
Installing Linkerd Using Flux¶
To install Linkerd we'll use a Kustomization file. It will allow us to specify the order and default namespace for the installed resources, and to generate Secrets from certificate files via the use of a secretGenerator.
To support mTLS connections between meshed pods, Linkerd requires a trust anchor certificate and an issuer certificate with its corresponding key. These certificates are automatically created via the linkerd install command. However, when using a Helm chart to install Linkerd, you must provide these certificates deliberately. The step CLI, listed above, allows us to generate these certificates.
To generate the trust anchor certificate, run:
step certificate create root.linkerd.cluster.local ca.crt ca.key \
+--profile root-ca --no-password --insecure
+To generate the issuer certificate, run:
step certificate create identity.linkerd.cluster.local issuer.crt issuer.key \
+--profile intermediate-ca --not-after 8760h --no-password --insecure \
+--ca ca.crt --ca-key ca.key
+Add the ca.crt, issuer.crt, and issuer.key files to the cluster repository under a linkerd directory.
Let's add the three manifests for Linkerd components under the ./linkerd directory: - A Namespace resource to control where the components are installed - A HelmRepository resource to make the Linkerd Helm repo available on the cluster - A HelmRelease resource to install the latest version of Linkerd from the HelmRepository
Expand to see and copy-paste the three Linkerd manifests to add
linkerd/namespace.yaml
---
+apiVersion: v1
+kind: Namespace
+metadata:
+name: linkerd
+labels:
+ config.linkerd.io/admission-webhooks: disabled
+linkerd/source.yaml
---
+apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: HelmRepository
+metadata:
+name: linkerd
+spec:
+interval: 1h
+url: https://helm.linkerd.io/stable
+Note: The value for the spec.values.identity.issuer.crtExpiry field below depends on the parameter value used during the creation of the issuer certificate. In this example, it should be set to one year from the certificate creation.
linkerd/releases.yaml
---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+name: linkerd
+spec:
+interval: 10m
+chart:
+ spec:
+ chart: linkerd2
+ reconcileStrategy: ChartVersion
+ sourceRef:
+ kind: HelmRepository
+ name: linkerd
+install:
+ crds: Create
+upgrade:
+ crds: CreateReplace
+valuesFrom:
+ - kind: Secret
+ name: linkerd-certs
+ valuesKey: ca.crt
+ targetPath: identityTrustAnchorsPEM
+ - kind: Secret
+ name: linkerd-certs
+ valuesKey: issuer.crt
+ targetPath: identity.issuer.tls.crtPEM
+ - kind: Secret
+ name: linkerd-certs
+ valuesKey: issuer.key
+ targetPath: identity.issuer.tls.keyPEM
+values:
+ installNamespace: false
+ identity:
+ issuer:
+ crtExpiry: "2023-07-18T20:00:00Z" # Change this to match generated certificate expiry date
+---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+name: linkerd-viz
+spec:
+interval: 10m
+dependsOn:
+ - name: linkerd
+chart:
+ spec:
+ chart: linkerd-viz
+ reconcileStrategy: ChartVersion
+ sourceRef:
+ kind: HelmRepository
+ name: linkerd
+Next, add the following manifests. The first file instructs Kustomize to patch any Secrets that are referenced in HelmRelease manifests. The second file is a Kustomization that references all the other linkerd resource files.
Expand to see the Linkerd Kustomization manifests
linkerd/kustomizeconfig.yaml
nameReference:
+- kind: Secret
+ version: v1
+ fieldSpecs:
+ - path: spec/valuesFrom/name
+ kind: HelmRelease
+linkerd/kustomization.yaml
---
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: linkerd
+configurations:
+- kustomizeconfig.yaml
+resources:
+- namespace.yaml
+- source.yaml
+- releases.yaml
+secretGenerator:
+- name: linkerd-certs
+ files:
+ - ca.crt
+ - issuer.crt
+ - issuer.key
+Note: The secretGenerator generates Secrets from the files you've just created.
At this point the linkerd directory in your cluster repository should look like this:
> tree linkerd
+linkerd
+├── ca.crt
+├── issuer.crt
+├── issuer.key
+├── kustomization.yaml
+├── kustomizeconfig.yaml
+├── namespace.yaml
+├── releases.yaml
+└── source.yaml
+Once Flux reconciles this directory to the cluster, Linkerd should be installed.
Before proceeding to the next step, check that all the Linkerd pods have started successfully:
> kubectl get pods -n linkerd
+NAME READY STATUS RESTARTS AGE
+linkerd-destination-66d5668b-4mw49 4/4 Running 0 10m
+linkerd-identity-6b4658c74b-6nc97 2/2 Running 0 10m
+linkerd-proxy-injector-6b76789cb4-8vqj4 2/2 Running 0 10m
+
+> kubectl get pods -n linkerd-viz
+NAME READY STATUS RESTARTS AGE
+grafana-db56d7cb4-xlnn4 2/2 Running 0 10m
+metrics-api-595c7b564-724ps 2/2 Running 0 10m
+prometheus-5d4dffff55-8fscd 2/2 Running 0 10m
+tap-6dcb89d487-5ns8n 2/2 Running 0 10m
+tap-injector-54895654bb-9xn7k 2/2 Running 0 10m
+web-6b6f65dbc7-wltdg 2/2 Running 0 10m
+Note
Any new directories that you add to the cluster repository while following this guide must be included in a path that Flux reconciles.
Installing Flagger Using Flux¶
To install Flagger, you'll use a Kustomization file that will define the installation order and provide a default namespace for the installed resources.
Create a new flagger directory. Make sure to locate it under a repository path that Flux reconciles.
Now add under this directory the three resource manifests for Flagger: - A Namespace resource to control where the components are installed - A HelmRepository resource to make the Flagger Helm repo available on the cluster - A HelmRelease resource to install the latest version of Flagger and the load tester app (which generates synthetic traffic during the analysis phase), from that HelmRepository
Expand to see the three Flagger resource manifests
flagger/namespace.yaml
---
+apiVersion: v1
+kind: Namespace
+metadata:
+name: flagger
+flagger/source.yaml
---
+apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: HelmRepository
+metadata:
+name: flagger
+spec:
+interval: 1h
+url: https://flagger.app
+flagger/releases.yaml
---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+name: flagger
+spec:
+releaseName: flagger
+install:
+ crds: Create
+upgrade:
+ crds: CreateReplace
+interval: 10m
+chart:
+ spec:
+ chart: flagger
+ reconcileStrategy: ChartVersion
+ sourceRef:
+ kind: HelmRepository
+ name: flagger
+values:
+ metricsServer: http://prometheus.linkerd-viz:9090
+ meshProvider: linkerd
+---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+name: loadtester
+spec:
+interval: 10m
+chart:
+ spec:
+ chart: loadtester
+ reconcileStrategy: ChartVersion
+ sourceRef:
+ kind: HelmRepository
+ name: flagger
+Now add the following Kustomization file. It references all of the previous files that you've added:
Expand to see the Flagger Kustomization manifest
flagger/kustomization.yaml
---
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: flagger
+resources:
+- namespace.yaml
+- source.yaml
+- releases.yaml
+The flagger directory in the cluster repository should look like this:
> tree flagger
+flagger
+├── kustomization.yaml
+├── namespace.yaml
+├── releases.yaml
+└── source.yaml
+Once Flux reconciles this directory to the cluster, Flagger and the load tester app should be installed.
Before proceeding to the next step, check that all of your Flagger pods have started successfully:
> kubectl get pods -n flagger
+NAME READY STATUS RESTARTS AGE
+flagger-7d456d4fc7-knf2g 1/1 Running 0 4m
+loadtester-855b4d77f6-scl6r 1/1 Running 0 4m
+Custom Resources Generated by Flagger¶
When Flagger is configured to integrate with a service mesh such as Linkerd or Istio for the rollout, this ClusterRole needs to be extended so that it can read the additional service mesh resources that Flagger generates. To display service mesh- or ingress-related resources, we require spec.provider to be set in each canary resource.
The following table provides a list of all the custom resources that Flagger generates grouped by provider:
| Provider | API Group | Resource |
|---|---|---|
| AppMesh | appmesh.k8s.aws | virtualnode |
| appmesh.k8s.aws | virtualrouter | |
| appmesh.k8s.aws | virtualservice | |
| Linkerd | split.smi-spec.io | trafficsplit |
| Istio | networking.istio.io | destinationrule |
| networking.istio.io | virtualservice | |
| Contour | projectcontour.io | httpproxy |
| Gloo | gateway.solo.io | routetable |
| gloo.solo.io | upstream | |
| Nginx | networking.k8s.io | ingress |
| Skipper | networking.k8s.io | ingress |
| Traefik | traefik.containo.us | traefikservice |
| Open Service Mesh | split.smi-spec.io | trafficsplit |
| Kuma | kuma.io | trafficroute |
| GatewayAPI | gateway.networking.k8s.io | httproute |
For example, the following manifest shows how gitops-canaries-reader has been extended to allow the user for viewing TrafficSplit resources when Linkerd is used:
Expand to see example canary reader RBAC
gitops-canaries-reader.yaml
apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+name: gitops-canaries-reader
+rules:
+- apiGroups:
+- flagger.app
+resources:
+- canaries
+- metrictemplates
+verbs:
+- get
+- list
+- apiGroups:
+- ""
+resources:
+- events
+verbs:
+- get
+- watch
+- list
+# Additional permissions for Linkerd resources are added below
+- apiGroups:
+- split.smi-spec.io
+resources:
+- trafficsplits
+verbs:
+- get
+- list
+Setting up Remote Cluster Permissions¶
In order to view canaries in a remote cluster from the management cluster, you need to consider the following: - The service account used to access the remote cluster needs to be able to list namespaces and custom resource definitions in the given cluster. It additionally needs to be able to impersonate users and groups. - The user or group that logs in to the management cluster, needs appropriate permissions to certain resources of the remote cluster.
For example, applying the following manifest on remote clusters, ensures that the wego-admin user will be able to view canary information from within the Weave GitOps Enterprise UI on the management cluster:
Expand to see example of remote cluster canary reader
remote-cluster-service-user-rbac.yaml
apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+name: user-groups-impersonator
+rules:
+- apiGroups: [""]
+ resources: ["users", "groups"]
+ verbs: ["impersonate"]
+- apiGroups: [""]
+ resources: ["namespaces"]
+ verbs: ["get", "list"]
+- apiGroups: ["apiextensions.k8s.io"]
+ resources: ["customresourcedefinitions"]
+ verbs: ["get", "list"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+name: impersonate-user-groups
+subjects:
+- kind: ServiceAccount
+ name: remote-cluster-01 # Service account created in remote cluster
+ namespace: default
+roleRef:
+kind: ClusterRole
+name: user-groups-impersonator
+apiGroup: rbac.authorization.k8s.io
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+name: canary-reader
+rules:
+- apiGroups: [""]
+ resources: [ "events", "services" ]
+ verbs: [ "get", "list", "watch" ]
+- apiGroups: [ "apps" ]
+ resources: [ "*" ]
+ verbs: [ "get", "list" ]
+- apiGroups: [ "autoscaling" ]
+ resources: [ "*" ]
+ verbs: [ "get", "list" ]
+- apiGroups: [ "flagger.app" ]
+ resources: [ "canaries", "metrictemplates"]
+ verbs: [ "get", "list", "watch" ]
+- apiGroups: [ "helm.toolkit.fluxcd.io" ]
+ resources: [ "helmreleases" ]
+ verbs: [ "get", "list" ]
+- apiGroups: [ "kustomize.toolkit.fluxcd.io" ]
+ resources: [ "kustomizations" ]
+ verbs: [ "get", "list" ]
+- apiGroups: [ "source.toolkit.fluxcd.io" ]
+ resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ]
+ verbs: [ "get", "list" ]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+name: read-canaries
+subjects:
+- kind: User
+name: wego-admin # User logged in management cluster, impersonated via service account
+apiGroup: rbac.authorization.k8s.io
+roleRef:
+kind: ClusterRole
+name: canary-reader
+apiGroup: rbac.authorization.k8s.io
+You may need to add more users/groups to the read-canaries ClusterRoleBinding to ensure additional users can view canary information from within the Weave GitOps Enterprise UI.
Deploy a Canary Release¶
To demonstrate the progressive rollout of an application, we'll use a tiny sample web app called podinfo and configure a canary release strategy.
In our example, Flagger will scale up a new version of podinfo (the canary) alongside the existing version (the primary). It will gradually increase traffic to the new version in increments of 5%, up to a maximum of 50%. Flagger will continuously monitor the new version for an acceptable request response rate and average request duration. Based on this analysis, Flagger will either update the primary to the new version or abandon the promotion, then scale the canary back down to zero.
Create a new test directory and add these three canary resource manifests under it: - A Namespace resource to control where the components are installed - A Deployment and HorizontalPodAutoscaler for the podinfo application - A Canary resource which references the Deployment and HorizontalPodAutoscaler resources
We don't need to define a service resource. This is specified within the canary definition and created by Flagger.
Expand to see the three canary resource manifests
test/namespace.yaml
---
+apiVersion: v1
+kind: Namespace
+metadata:
+name: test
+annotations:
+ linkerd.io/inject: enabled
+test/deployment.yaml
---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+name: podinfo
+labels:
+ app: podinfo
+spec:
+minReadySeconds: 5
+revisionHistoryLimit: 5
+progressDeadlineSeconds: 60
+strategy:
+ rollingUpdate:
+ maxUnavailable: 1
+ type: RollingUpdate
+selector:
+ matchLabels:
+ app: podinfo
+template:
+ metadata:
+ annotations:
+ prometheus.io/scrape: "true"
+ prometheus.io/port: "9797"
+ labels:
+ app: podinfo
+ spec:
+ containers:
+ - name: podinfod
+ image: ghcr.io/stefanprodan/podinfo:6.1.8
+ imagePullPolicy: IfNotPresent
+ ports:
+ - name: http
+ containerPort: 9898
+ protocol: TCP
+ - name: http-metrics
+ containerPort: 9797
+ protocol: TCP
+ - name: grpc
+ containerPort: 9999
+ protocol: TCP
+ command:
+ - ./podinfo
+ - --port=9898
+ - --port-metrics=9797
+ - --grpc-port=9999
+ - --grpc-service-name=podinfo
+ - --level=info
+ - --random-delay=false
+ - --random-error=false
+ env:
+ - name: PODINFO_UI_COLOR
+ value: "#34577c"
+ livenessProbe:
+ exec:
+ command:
+ - podcli
+ - check
+ - http
+ - localhost:9898/healthz
+ initialDelaySeconds: 5
+ timeoutSeconds: 5
+ readinessProbe:
+ exec:
+ command:
+ - podcli
+ - check
+ - http
+ - localhost:9898/readyz
+ initialDelaySeconds: 5
+ timeoutSeconds: 5
+ resources:
+ limits:
+ cpu: 2000m
+ memory: 512Mi
+ requests:
+ cpu: 100m
+ memory: 64Mi
+
+---
+apiVersion: autoscaling/v2beta2
+kind: HorizontalPodAutoscaler
+metadata:
+name: podinfo
+spec:
+scaleTargetRef:
+ apiVersion: apps/v1
+ kind: Deployment
+ name: podinfo
+minReplicas: 2
+maxReplicas: 4
+metrics:
+ - type: Resource
+ resource:
+ name: cpu
+ target:
+ type: Utilization
+ # scale up if usage is above
+ # 99% of the requested CPU (100m)
+ averageUtilization: 99
+test/canary.yaml
---
+apiVersion: flagger.app/v1beta1
+kind: Canary
+metadata:
+name: podinfo
+spec:
+# deployment reference
+targetRef:
+ apiVersion: apps/v1
+ kind: Deployment
+ name: podinfo
+# HPA reference (optional)
+autoscalerRef:
+ apiVersion: autoscaling/v2beta2
+ kind: HorizontalPodAutoscaler
+ name: podinfo
+# the maximum time in seconds for the canary deployment
+# to make progress before it is rollback (default 600s)
+progressDeadlineSeconds: 60
+service:
+ # ClusterIP port number
+ port: 9898
+ # container port number or name (optional)
+ targetPort: 9898
+analysis:
+ # schedule interval (default 60s)
+ interval: 30s
+ # max number of failed metric checks before rollback
+ threshold: 5
+ # max traffic percentage routed to canary
+ # percentage (0-100)
+ maxWeight: 50
+ # canary increment step
+ # percentage (0-100)
+ stepWeight: 5
+ # Linkerd Prometheus checks
+ metrics:
+ - name: request-success-rate
+ # minimum req success rate (non 5xx responses)
+ # percentage (0-100)
+ thresholdRange:
+ min: 99
+ interval: 1m
+ - name: request-duration
+ # maximum req duration P99
+ # milliseconds
+ thresholdRange:
+ max: 500
+ interval: 30s
+ # testing (optional)
+ webhooks:
+ - name: acceptance-test
+ type: pre-rollout
+ url: http://loadtester.flagger/
+ timeout: 30s
+ metadata:
+ type: bash
+ cmd: "curl -sd 'test' http://podinfo-canary.test:9898/token | grep token"
+ - name: load-test
+ type: rollout
+ url: http://loadtester.flagger/
+ metadata:
+ cmd: "hey -z 2m -q 10 -c 2 http://podinfo-canary.test:9898/"
+Add a Kustomization file to apply all resources to the test namespace:
Expand to see the Canary Kustomization manifest
test/kustomization.yaml
---
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: test
+resources:
+- namespace.yaml
+- deployment.yaml
+- canary.yaml
+At this point, the test directory in the cluster repository should look like this:
> tree test
+test
+├── canary.yaml
+├── deployment.yaml
+├── kustomization.yaml
+└── namespace.yaml
+After a short time, the status of the canary object should be set to Initialized:
> kubectl get canary podinfo -n test
+NAME STATUS WEIGHT LASTTRANSITIONTIME
+podinfo Initialized 0 2022-07-22T12:37:58Z
+Trigger a new rollout by bumping the version of podinfo:
> kubectl set image deployment/podinfo podinfod=ghcr.io/stefanprodan/podinfo:6.0.1 -n test
+During the progressive rollout, the canary object reports on its current status:
> kubectl get canary podinfo -n test
+NAME STATUS WEIGHT LASTTRANSITIONTIME
+podinfo Progressing 5 2022-07-22T12:41:57Z
+After a short time the rollout is completed and the status of the canary object is set to Succeeded:
> kubectl get canary podinfo -n test
+NAME STATUS WEIGHT LASTTRANSITIONTIME
+podinfo Succeeded 0 2022-07-22T12:47:58Z
+Summary¶
Congratulations, you have now completed a progressive delivery rollout with Flagger and Linkerd!
Next steps: - Explore more of what Flagger offers - Configure manual approvals for progressive delivery deployments
Gitops
gitops¶
Weave GitOps
Synopsis¶
Command line utility for managing Kubernetes applications via GitOps.
Examples¶
# Get help for gitops create dashboard command
+ gitops create dashboard -h
+ gitops help create dashboard
+
+ # Get the version of gitops along with commit, branch, and flux version
+ gitops version
+
+ To learn more, you can find our documentation at https://docs.gitops.weave.works/
+Options¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ -h, --help help for gitops
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops check
gitops check¶
Validates flux compatibility
gitops check [flags]
+Examples¶
# Validate flux and kubernetes compatibility
+gitops check
+Options¶
-h, --help help for check
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops completion
gitops completion¶
Generate the autocompletion script for the specified shell
Synopsis¶
Generate the autocompletion script for gitops for the specified shell. See each sub-command's help for details on how to use the generated script.
Options¶
-h, --help help for completion
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops completion bash
gitops completion bash¶
Generate the autocompletion script for bash
Synopsis¶
Generate the autocompletion script for the bash shell.
This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager.
To load completions in your current shell session:
1 | |
To load completions for every new session, execute once:
Linux:¶
1 | |
macOS:¶
1 | |
You will need to start a new shell for this setup to take effect.
gitops completion bash
+Options¶
-h, --help help for bash
+ --no-descriptions disable completion descriptions
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops completion fish
gitops completion fish¶
Generate the autocompletion script for fish
Synopsis¶
Generate the autocompletion script for the fish shell.
To load completions in your current shell session:
1 | |
To load completions for every new session, execute once:
1 | |
You will need to start a new shell for this setup to take effect.
gitops completion fish [flags]
+Options¶
-h, --help help for fish
+ --no-descriptions disable completion descriptions
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops completion powershell
gitops completion powershell¶
Generate the autocompletion script for powershell
Synopsis¶
Generate the autocompletion script for powershell.
To load completions in your current shell session:
1 | |
To load completions for every new session, add the output of the above command to your powershell profile.
gitops completion powershell [flags]
+Options¶
-h, --help help for powershell
+ --no-descriptions disable completion descriptions
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops completion zsh
gitops completion zsh¶
Generate the autocompletion script for zsh
Synopsis¶
Generate the autocompletion script for the zsh shell.
If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:
1 | |
To load completions in your current shell session:
1 | |
To load completions for every new session, execute once:
Linux:¶
1 | |
macOS:¶
1 | |
You will need to start a new shell for this setup to take effect.
gitops completion zsh [flags]
+Options¶
-h, --help help for zsh
+ --no-descriptions disable completion descriptions
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops create
gitops create¶
Creates a resource
Examples¶
# Create a HelmRepository and HelmRelease to deploy Weave GitOps
+gitops create dashboard ww-gitops \
+ --password=$PASSWORD \
+ --export > ./clusters/my-cluster/weave-gitops-dashboard.yaml
+
+# Create a Terraform object
+gitops create terraform my-resource \
+ -n my-namespace \
+ --source GitRepository/my-project \
+ --path ./terraform \
+ --interval 1m \
+ --export > ./clusters/my-cluster/infra/terraform-my-resource.yaml
+Options¶
--export Export in YAML format to stdout.
+ -h, --help help for create
+ --timeout duration The timeout for operations during resource creation. (default 3m0s)
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops create dashboard
gitops create dashboard¶
Create a HelmRepository and HelmRelease to deploy Weave GitOps
Synopsis¶
Create a HelmRepository and HelmRelease to deploy Weave GitOps
gitops create dashboard [flags]
+Examples¶
# Create a HelmRepository and HelmRelease to deploy Weave GitOps
+gitops create dashboard ww-gitops \
+ --password=$PASSWORD \
+ --export > ./clusters/my-cluster/weave-gitops-dashboard.yaml
+Options¶
--context string The name of the kubeconfig context to use
+ --disable-compression If true, opt-out of response compression for all requests to the server
+ -h, --help help for dashboard
+ --password string The password of the dashboard admin user.
+ --username string The username of the dashboard admin user. (default "admin")
+ --values strings Local path to values.yaml files for HelmRelease, also accepts comma-separated values.
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --export Export in YAML format to stdout.
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ --timeout duration The timeout for operations during resource creation. (default 3m0s)
+SEE ALSO¶
Gitops create terraform
gitops create terraform¶
Create a Terraform object
Synopsis¶
Create a Terraform object
gitops create terraform [flags]
+Examples¶
# Create a Terraform resource in the default namespace
+gitops create terraform -n default my-resource --source GitRepository/my-project --path ./terraform --interval 15m
+
+# Create and export a Terraform resource manifest to the standard output
+gitops create terraform -n default my-resource --source GitRepository/my-project --path ./terraform --interval 15m --export
+Options¶
--context string The name of the kubeconfig context to use
+ --disable-compression If true, opt-out of response compression for all requests to the server
+ -h, --help help for terraform
+ --interval string Interval at which the Terraform configuration should be applied
+ --path string Path to the Terraform configuration
+ --source string Source of the Terraform configuration
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --export Export in YAML format to stdout.
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ --timeout duration The timeout for operations during resource creation. (default 3m0s)
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops delete
gitops delete¶
Delete a resource
Options¶
-h, --help help for delete
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops delete terraform
gitops delete terraform¶
Delete a Terraform object
gitops delete terraform [flags]
+Examples¶
# Delete a Terraform resource in the default namespace
+gitops delete terraform -n default my-resource
+Options¶
--context string The name of the kubeconfig context to use
+ --disable-compression If true, opt-out of response compression for all requests to the server
+ -h, --help help for terraform
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops get
gitops get¶
Display one or many Weave GitOps resources
Examples¶
# Get the CLI configuration for Weave GitOps
+gitops get config
+
+# Generate a hashed secret
+PASSWORD="<your password>"
+echo -n $PASSWORD | gitops get bcrypt-hash
+Options¶
-h, --help help for get
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops get bcrypt hash
gitops get bcrypt-hash¶
Generates a hashed secret
gitops get bcrypt-hash [flags]
+Examples¶
PASSWORD="<your password>"
+echo -n $PASSWORD | gitops get bcrypt-hash
+Options¶
-h, --help help for bcrypt-hash
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops get config
gitops get config¶
Prints out the CLI configuration for Weave GitOps
gitops get config [flags]
+Examples¶
# Prints out the CLI configuration for Weave GitOps
+gitops get config
+Options¶
-h, --help help for config
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Gitops logs
gitops logs¶
Get logs for a resource
Options¶
-h, --help help for logs
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops logs terraform
gitops logs terraform¶
Get the runner logs of a Terraform object
gitops logs terraform [flags]
+Examples¶
# Get the runner logs of a Terraform object in the "flux-system" namespace
+gitops logs terraform --namespace flux-system my-resource
+Options¶
--context string The name of the kubeconfig context to use
+ --disable-compression If true, opt-out of response compression for all requests to the server
+ -h, --help help for terraform
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops replan
gitops replan¶
Replan a resource
Examples¶
# Replan the Terraform plan of a Terraform object from the "flux-system" namespace
+gitops replan terraform --namespace flux-system my-resource
+Options¶
-h, --help help for replan
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops replan terraform
gitops replan terraform¶
Trigger replan for a Terraform object
gitops replan terraform [flags]
+Examples¶
# Replan the Terraform plan of a Terraform object from the "flux-system" namespace
+gitops replan terraform --namespace flux-system my-resource
+Options¶
--context string The name of the kubeconfig context to use
+ --disable-compression If true, opt-out of response compression for all requests to the server
+ -h, --help help for terraform
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops resume
gitops resume¶
Resume a resource
Examples¶
# Suspend a Terraform object from the "flux-system" namespace
+gitops resume terraform --namespace flux-system my-resource
+Options¶
-h, --help help for resume
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops resume terraform
gitops resume terraform¶
Resume a Terraform object
gitops resume terraform [flags]
+Examples¶
# Resume a Terraform object in the "flux-system" namespace
+gitops resume terraform --namespace flux-system my-resource
+Options¶
--context string The name of the kubeconfig context to use
+ --disable-compression If true, opt-out of response compression for all requests to the server
+ -h, --help help for terraform
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops set
gitops set¶
Sets one or many Weave GitOps CLI configs or resources
Examples¶
# Enables analytics in the current user's CLI configuration for Weave GitOps
+gitops set config analytics true
+Options¶
-h, --help help for set
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops set config
gitops set config¶
Set the CLI configuration for Weave GitOps
gitops set config [flags]
+Examples¶
# Enables analytics in the current user's CLI configuration for Weave GitOps
+gitops set config analytics true
+Options¶
-h, --help help for config
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Gitops suspend
gitops suspend¶
Suspend a resource
Examples¶
# Suspend a Terraform object in the "flux-system" namespace
+gitops resume terraform --namespace flux-system my-resource
+Options¶
-h, --help help for suspend
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops suspend terraform
gitops suspend terraform¶
Suspend a Terraform object
gitops suspend terraform [flags]
+Examples¶
# Suspend a Terraform object in the "flux-system" namespace
+gitops suspend terraform --namespace flux-system my-resource
+Options¶
--context string The name of the kubeconfig context to use
+ --disable-compression If true, opt-out of response compression for all requests to the server
+ -h, --help help for terraform
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Gitops version
gitops version¶
Display gitops version
gitops version [flags]
+Options¶
-h, --help help for version
+Options inherited from parent commands¶
-e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable
+ --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+ --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.
+ -n, --namespace string The namespace scope for this operation (default "flux-system")
+ -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable
+ -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable
+SEE ALSO¶
Auto generated by spf13/cobra on 9-Nov-2023¶
Helm chart reference¶
This is a reference of all the configurable values in Weave GitOps's Helm chart. This is intended for customizing your installation after you've gone through the getting started guide.
This reference was generated for the chart version 4.0.34 which installs weave gitops v0.36.0.
Values¶
| Key | Type | Default | Description |
|---|---|---|---|
| additionalArgs | list | [] | Additional arguments to pass in to the gitops-server |
| adminUser.create | bool | false | Whether the local admin user should be created. If you use this make sure you add it to rbac.impersonationResourceNames. |
| adminUser.createClusterRole | bool | true | Specifies whether the clusterRole & binding to the admin user should be created. Will be created only if adminUser.create is enabled. Without this, the adminUser will only be able to see resources in the target namespace. |
| adminUser.createSecret | bool | true | Whether we should create the secret for the local adminUser. Will be created only if adminUser.create is enabled. Without this, we'll still set up the roles and permissions, but the secret with username and password has to be provided separately. |
| adminUser.passwordHash | string | nil | Set the password for local admin user. Requires adminUser.create and adminUser.createSecret This needs to have been hashed using bcrypt. You can do this via our CLI with gitops get bcrypt-hash. |
| adminUser.username | string | "gitops-test-user" | Set username for local admin user, this should match the value in the secret cluster-user-auth which can be created with adminUser.createSecret. Requires adminUser.create. |
| affinity | object | {} | |
| annotations | object | {} | Annotations to add to the deployment |
| envVars[0].name | string | "WEAVE_GITOPS_FEATURE_TENANCY" | |
| envVars[0].value | string | "true" | |
| envVars[1].name | string | "WEAVE_GITOPS_FEATURE_CLUSTER" | |
| envVars[1].value | string | "false" | |
| extraVolumeMounts | list | [] | |
| extraVolumes | list | [] | |
| fullnameOverride | string | "" | |
| image.pullPolicy | string | "IfNotPresent" | |
| image.repository | string | "ghcr.io/weaveworks/wego-app" | |
| image.tag | string | "v0.36.0" | |
| imagePullSecrets | list | [] | |
| ingress.annotations | object | {} | |
| ingress.className | string | "" | |
| ingress.enabled | bool | false | |
| ingress.hosts | string | nil | |
| ingress.tls | list | [] | |
| logLevel | string | "info" | What log level to output. Valid levels are 'debug', 'info', 'warn' and 'error' |
| metrics.enabled | bool | false | Start the metrics exporter |
| metrics.service.annotations | object | {"prometheus.io/path":"/metrics","prometheus.io/port":"{{ .Values.metrics.service.port }}","prometheus.io/scrape":"true"} | Annotations to set on the service |
| metrics.service.port | int | 2112 | Port to start the metrics exporter on |
| nameOverride | string | "" | |
| networkPolicy.create | bool | true | Specifies whether default network policies should be created. |
| nodeSelector | object | {} | |
| oidcSecret.create | bool | false | |
| podAnnotations | object | {} | |
| podLabels | object | {} | |
| podSecurityContext | object | {} | |
| rbac.additionalRules | list | [] | If non-empty, these additional rules will be appended to the RBAC role and the cluster role. for example, additionalRules: - apiGroups: ["infra.contrib.fluxcd.io"] resources: ["terraforms"] verbs: [ "get", "list", "patch" ] |
| rbac.create | bool | true | Specifies whether the clusterRole & binding to the service account should be created |
| rbac.impersonationResourceNames | list | [] | If non-empty, this limits the resources that the service account can impersonate. This applies to both users and groups, e.g. ['user1@corporation.com', 'user2@corporation.com', 'operations'] |
| rbac.impersonationResources | list | ["users","groups"] | Limit the type of principal that can be impersonated |
| rbac.viewSecretsResourceNames | list | ["cluster-user-auth","oidc-auth"] | If non-empty, this limits the secrets that can be accessed by the service account to the specified ones, e.g. ['weave-gitops-enterprise-credentials'] |
| replicaCount | int | 1 | |
| resources | object | {} | |
| securityContext.allowPrivilegeEscalation | bool | false | |
| securityContext.capabilities.drop[0] | string | "ALL" | |
| securityContext.readOnlyRootFilesystem | bool | true | |
| securityContext.runAsNonRoot | bool | true | |
| securityContext.runAsUser | int | 1000 | |
| securityContext.seccompProfile.type | string | "RuntimeDefault" | |
| serverTLS.enable | bool | false | Enable TLS termination in gitops itself. If you enable this, you need to create a secret, and specify the secretName. Another option is to create an ingress. |
| serverTLS.secretName | string | "my-secret-tls" | Specify the tls secret name. This type of secrets have a key called tls.crt and tls.key containing their corresponding values in base64 format. See https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets for more details and examples |
| service.annotations | object | {} | |
| service.create | bool | true | |
| service.port | int | 9001 | |
| service.type | string | "ClusterIP" | |
| serviceAccount.annotations | object | {} | Annotations to add to the service account |
| serviceAccount.create | bool | true | Specifies whether a service account should be created |
| serviceAccount.name | string | "" | The name of the service account to use. If not set and create is true, a name is generated using the fullname template |
| tolerations | list | [] |
For full documentation visit mkdocs.org and Material theme for mkdocs. Follow the installation instructions here https://squidfunk.github.io/mkdocs-material/getting-started/
"},{"location":"#commands","title":"Commands","text":"Under the folder userdocs mkdocs.yml # The configuration file. docs/ index.md # The documentation homepage. ... # Other markdown pages, images and other files.
Are you running Backstage and Flux? Do you want to expose the state of your Flux resources in your Backstage portal?
The @weaveworksoss/backstage-plugin-flux Backstage plugin provides a set of components that you can add to your existing Backstage app to display the state of Flux resources.
We provide the full installation instructions in the plugin repository. But first you will need to install the Kubernetes plugin and configure it to access the clusters you want to query Flux resources from.
You will need to install the plugin to your frontend app:
# From your Backstage root directory\nyarn add --cwd packages/app @weaveworksoss/backstage-plugin-flux\nThen add the components you want to your EntityPage.
Currently, the Backstage plugin provides the following components:
For example, to add the EntityFluxHelmReleasesCard to your Entity home page for components with the backstage.io/kubernetes-id entity annotation.
import {\n EntityFluxHelmReleasesCard,\n} from '@weaveworksoss/backstage-plugin-flux';\nimport { isKubernetesAvailable } from '@backstage/plugin-kubernetes';\n\nconst overviewContent = (\n <Grid item md={6}>\n <EntityAboutCard variant=\"gridItem\" />\n </Grid>\n\n <EntitySwitch>\n <EntitySwitch.Case if={isKubernetesAvailable}>\n <EntityFluxHelmReleasesCard />\n </EntitySwitch.Case>\n </EntitySwitch>\n);\nWhen you view components with the correct annotation:
apiVersion: backstage.io/v1alpha1\nkind: Component\nmetadata:\nname: catalogue-service\ndescription: A microservices-demo service that provides catalogue/product information\nannotations:\nbackstage.io/kubernetes-id: podinfo\nThis will query across your configured clusters for HelmReleases that have the correct label:
apiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: podinfo\nnamespace: podinfo\n# The label here is matched to the Backstage Entity annotation\nlabels:\nbackstage.io/kubernetes-id: podinfo\nspec:\ninterval: 5m\nchart:\nspec:\nchart: podinfo\nversion: '6.3.6'\nsourceRef:\nkind: HelmRepository\nname: podinfo\nnamespace: podinfo\nInstead of displaying the state on the overview page, it's possible to compose a page displaying the state of resources.
For example, to add a page /kustomizations to your Entity for components with the backstage.io/kubernetes-id entity annotation:
import {\n EntityFluxGitRepositoriesCard,\n EntityFluxKustomizationsCard,\n} from '@weaveworksoss/backstage-plugin-flux';\nimport { isKubernetesAvailable } from '@backstage/plugin-kubernetes';\n\nconst serviceEntityPage = (\n // insert in the page where you need it\n\n <EntityLayout.Route path=\"/kustomizations\" title=\"Kustomizations\" if={isKubernetesAvailable}>\n <Grid container spacing={3} alignItems=\"stretch\">\n <Grid item md={12}>\n <EntityFluxKustomizationsCard />\n </Grid>\n <Grid item md={12}>\n <EntityFluxGitRepositoriesCard />\n </Grid>\n </Grid>\n </EntityLayout.Route>\n);\nYou can connect the plugin to your Weave GitOps installation through your config:
app-config.yamlapp:\ntitle: Backstage Example App\nbaseUrl: http://localhost:3000\n...\ngitops:\n# Set this to be the root of your Weave GitOps application\nbaseUrl: https://example.com\nNOTE: The plugin will generate URLs relative to this URL and link to them from the displayed resources.
"},{"location":"feedback-and-telemetry/","title":"Feedback and Telemetry","text":""},{"location":"feedback-and-telemetry/#feedback","title":"Feedback","text":"We \u2764\ufe0f your comments and suggestions as we look to make successfully adopting a cloud-native approach, to application deployment on Kubernetes with GitOps, easier and easier. There are a number of ways you can reach out:
Weaveworks is utilizing Pendo, a product-analytics app, to gather anonymous user behavior analytics for both Weave GitOps and Weave GitOps Enterprise. We use this data so we can understand what you love about Weave GitOps, and areas we can improve.
Weave GitOps OSS users will be notified when you create the dashboard for the first time via gitops create dashboard or when you use gitops run for the first time and decide to install the dashboard via that functionality. Analytics will not be enabled until after this notification so that you can opt out before sending analytics data.
For Weave GitOps Enterprise users, this functionality is turned on by default. Further below we go into more detail about how you can control this functionality.
"},{"location":"feedback-and-telemetry/#why-are-we-collecting-this-data","title":"Why are we collecting this data?","text":"We want to ensure that we are designing the best features, addressing the most pressing bugs, and prioritizing our roadmap appropriately for our users. Collecting analytics on our users\u2019 behaviors gives us valuable insights and allows us to conduct analyses on user behavior within the product. This is important for us so we can make informed decisions- based on how, where and when our users use Weave GitOps - and prioritize what is most important to users like you.
"},{"location":"feedback-and-telemetry/#for-example","title":"For example","text":"We\u2019d like to understand the usage of the graph and dependency tabs within the dashboard. If users are utilizing this feature, we would like to understand the value and how we can improve that feature. However, if users aren\u2019t using it, we can conduct research to understand why and either fix it, or come to the conclusion that it really doesn\u2019t serve any utility and focus our efforts on more valuable features.
"},{"location":"feedback-and-telemetry/#how-long-is-the-collected-data-stored","title":"How long is the collected data stored?","text":"Weave GitOps\u2019s anonymous user and event data has a 24 month retention policy. The default value for data retention in Pendo is 7 years. For more information on Pendo\u2019s data storage policies, click here.
"},{"location":"feedback-and-telemetry/#what-are-we-collecting","title":"What are we collecting?","text":"Weave GitOps gathers data on how the CLI and Web UI are used. There is no way for us or Pendo to connect our IDs to individual users or sites.
For the CLI, we gather usage data on:
For the Web UI, we gather usage data on:
Weave GitOps CLI analytics are sent at startup. The dashboard analytics are sent through its execution. Both CLI and Dashboard analytics are sent to Pendo over HTTPS.
"},{"location":"feedback-and-telemetry/#how","title":"How?","text":"The CLI code is viewable in pkg/analytics. It will ignore any errors, e.g. if you don\u2019t have any network connection.
The dashboard setup code is viewable in ui/components/Pendo.tsx - this will fetch a 3rd party javascript from Pendo\u2019s servers.
"},{"location":"feedback-and-telemetry/#opting-out","title":"Opting out","text":"All the data collected, analytics, and feedback are for the sole purpose of creating better product experience for you and your teams. We would really appreciate it if you left the analytics on as it helps us prioritize which features to build next and what features to improve. However, if you do want to opt out of Weave GitOps\u2019s analytics you can opt out of CLI and/or Dashboard analytics.
"},{"location":"feedback-and-telemetry/#cli","title":"CLI","text":"We have created a command to make it easy to turn analytics on or off for the CLI.
To disable analytics: gitops set config analytics false
To enable analytics: gitops set config analytics true
"},{"location":"feedback-and-telemetry/#dashboard","title":"Dashboard","text":"You need to update your helm release to remove WEAVE_GITOPS_FEATURE_TELEMETRY from the envVars value.
\ud83d\udc4b Come talk to us and other users in the #weave-gitops channel on Weaveworks Community Slack.
Invite yourself if you haven't joined yet.
"},{"location":"help-and-support/#flux","title":"Flux","text":"The Flux project has a fantastic community to help support your GitOps journey, find more details on how to reach out via their community page
"},{"location":"help-and-support/#commercial-support","title":"Commercial Support","text":"Weaveworks provides Weave GitOps Enterprise, a continuous operations product that makes it easy to deploy and manage Kubernetes clusters and applications at scale in any environment. The single management console automates trusted application delivery and secure infrastructure operations on premise, in the cloud and at the edge.
To discuss your support needs, please contact us at sales@weave.works.
"},{"location":"help-and-support/#recommended-resources","title":"Recommended resources","text":"Got a suggestion for this list? Please open a pull request using the \"Edit this page\" link at the bottom.
"},{"location":"help-and-support/#weaveworks-materials","title":"Weaveworks materials","text":"\"GitOps is the best thing since configuration as code. Git changed how we collaborate, but declarative configuration is the key to dealing with infrastructure at scale, and sets the stage for the next generation of management tools\"
- Kelsey Hightower, Staff Developer Advocate, Google.
Weave GitOps improves developer experience\u2014simplifying the complexities and cognitive load of deploying and managing cloud native apps on Kubernetes so that teams can go faster. It\u2019s a powerful extension of Flux, a leading GitOps engine and Cloud Native Computing Foundation project. Weaveworks are the creators of Flux.
Weave GitOps\u2019 intuitive user interface surfaces key information to help application operators easily discover and resolve issues\u2014simplifying and scaling adoption of GitOps and continuous delivery. The UI provides a guided experience that helps users to easily discover the relationships between Flux objects and build understanding while providing insights into application deployments.
Today Weave GitOps defaults are Flux, Kustomize, Helm, SOPS, and Kubernetes Cluster API. If you use Flux already, then you can easily add Weave GitOps to create a platform management overlay.
Tip
Adopting GitOps can bring a number of key benefits\u2014including faster and more frequent deployments, easy recovery from failures, and improved security and auditabiity. Check out our GitOps for Absolute Beginners eBook and Guide to GitOps for more information.
"},{"location":"intro-weave-gitops/#getting-started","title":"Getting Started","text":"This user guide provides content that will help you to install and get started with our free and paid offerings: - Weave GitOps Open Source: a simple, open source developer platform for people who don't have Kubernetes expertise but who want cloud native applications. It includes the UI and many other features that take your team beyond a simple CI/CD system. Experience how easy it is to enable GitOps and run your apps in a cluster. Go here to install. - Weave GitOps Enterprise: an enterprise version that adds automation and 100% verifiable trust to existing developer platforms, enabling faster and more frequent deployments with guardrails and golden paths for every app team. Note that Enterprise offers a more robust UI than what you'll find in our open source version. Go here to install.
Tip
Want to learn more about how Weave GitOps Enterprise can help your team? Get in touch with sales@weave.works to discuss your needs.
Weave GitOps works on any Chromium-based browser (Chrome, Opera, Microsoft Edge), Safari, and Firefox. We only support the latest and prior two versions of these browsers.
To give Weave GitOps a test drive, we recommend checking out the Open Source version and its UI, then deploying an application. Let's take a closer look at the features it offers you, all for free.
"},{"location":"intro-weave-gitops/#weave-gitops-open-source-features","title":"Weave GitOps Open Source Features","text":"Like our Enterprise version, Weave GitOps Open Source fully integrates with Flux as the GitOps engine to provide:
Some of the things you can do with it:
OK, time to install!
"},{"location":"monitoring/","title":"Monitoring ENTERPRISE","text":"Weave GitOps Enterprise provides monitoring telemetry and tooling for metrics and profiling. WGE generates Prometheus metrics for monitoring both performance and business operations.
"},{"location":"monitoring/#setup","title":"Setup","text":"The following configuration options are available for you to configure monitoring:
---\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: weave-gitops-enterprise\nnamespace: flux-system\nspec:\nvalues:\nmonitoring:\nenabled: true # enable it if you want to expose a monitoring server\nservice:\nname: monitoring\nport: 8080 # port to expose the monitoring server\nmetrics:\nenabled: true # enable it to expose a prometheus metrics endpoint in `/metrics`\nprofiling:\nenabled: false # enable it to expose a pprof debug endpoint `/debug/pprof`\nWarning
The monitoring server holds private services, so you probably won't need to expose anything beyond your cluster. If you must, ensure that it is properly secured.
"},{"location":"monitoring/#get-started-with-monitoring","title":"Get Started with Monitoring","text":"This setup follows the same monitoring approach as Flux and is based on Prometheus Operator. Adapt it to your context as needed.
apiVersion: source.toolkit.fluxcd.io/v1\nkind: GitRepository\nmetadata:\nname: weave-gitops-quickstart\nnamespace: flux-system\nspec:\ninterval: 10m0s\nref:\nbranch: main\nurl: https://github.com/weaveworks/weave-gitops-quickstart\n---\napiVersion: v1\nkind: Namespace\nmetadata:\nname: monitoring\n---\napiVersion: kustomize.toolkit.fluxcd.io/v1\nkind: Kustomization\nmetadata:\nname: kube-prometheus-stack\nnamespace: flux-system\nspec:\ninterval: 10m0s\nsourceRef:\nkind: GitRepository\nname: weave-gitops-quickstart\npath: ./monitoring/kube-prometheus-stack\nprune: true\ntargetNamespace: monitoring\nwait: true\napiVersion: kustomize.toolkit.fluxcd.io/v1\nkind: Kustomization\nmetadata:\nname: monitoring-config\nnamespace: flux-system\nspec:\ninterval: 10m0s\nsourceRef:\nkind: GitRepository\nname: weave-gitops-quickstart\npath: ./monitoring/weave-gitops\ndependsOn:\n- name: kube-prometheus-stack\nprune: true\ntargetNamespace: monitoring\nWeave GitOps Overview
Monitor Weave GitOps golden signals for API server and controllers:
Weave GitOps Runtime
Monitor Weave GitOps Go runtime metrics like memory usage, memory heap, and Goroutines, among others.
Explorer
You can also monitor Explorer golden signals.
"},{"location":"monitoring/#profiling","title":"Profiling","text":"During operations, profiling is useful for gaining a deeper understanding of how Weave GitOps runtime behaves. Given that Weave GitOps is written in Go, profiling happens through pprof. It is exposed as a web endpoint by pprof http.
"},{"location":"monitoring/#get-started-with-profiling","title":"Get Started with Profiling","text":"Go here for more info on using pprof.
This document defines security reporting, handling, disclosure, and audit information for Weave Gitops.
"},{"location":"security/#security-process","title":"Security Process","text":""},{"location":"security/#report-a-vulnerability","title":"Report a Vulnerability","text":"Vulnerability disclosures announced publicly. Disclosures will contain an overview, details about the vulnerability, a fix that will typically be an update, and optionally a workaround if one is available.
We will coordinate publishing disclosures and security releases in a way that is realistic and necessary for end users. We prefer to fully disclose the vulnerability as soon as possible once a user mitigation is available. Disclosures will always be published in a timely manner after a release is published that fixes the vulnerability.
"},{"location":"security/#advisories","title":"Advisories","text":"Here is an overview of all our published security advisories.
"},{"location":"security/#weave-gitops-oss","title":"Weave Gitops OSS","text":"Date CVE Security Advisory Severity Affected version(s) 2022-06-23 CVE-2022-31098 Weave GitOps leaked cluster credentials into logs on connection errors Critical <= 0.8.1-rc.5"},{"location":"security/#weave-gitops-enterprise","title":"Weave Gitops Enterprise","text":"Date CVE Security Advisory Severity Affected version(s) 2022-08-27 CVE-2022-38790 Malicious links can be crafted by users and shown in the UI Critical < v0.9.0-rc.5"},{"location":"cluster-management/","title":"Cluster Management Introduction ENTERPRISE","text":"In line with the mantra \u201ccattle, not pets,\u201d Weave GitOps Enterprise (WGE) simplifies managing cluster lifecycle at scale\u2014even massive scale. Through pull requests, which make every action recorded and auditable, WGE makes it possible for teams to create, update, and delete clusters across entire fleets. Breaking things is harder, and recovery is easier. WGE further simplifies the cluster lifecycle management process by providing both a user interface (UI) and a command line interface (CLI) to interact with and manage clusters on-prem, across clouds, and in hybrid environments. You can even use our UI to delete clusters\u2014all it takes is the press of a button that spins up a pull request.
WGE fully supports a range of options, including: - Crossplane integration - Terraform integration, with a Terraform Controller that follows the patterns established by Flux - Cluster API
"},{"location":"cluster-management/#helm-charts-and-kustomizations-made-easy-with-our-ui","title":"Helm Charts and Kustomizations Made Easy with Our UI","text":"The Weave GitOps Enterprise UI enables you to install software packages to your bootstrapped cluster via the Applications view of our user interface, using a Helm chart (via a HelmRelease) or Kustomization. First, find the \"Add an Application\" button:
A form will appear, asking you to select the target cluster where you want to add your Application.
Select the source type of either your Git repository or your Helm repository from the selected cluster:
If you select Git repository as the source type, you will be able to add the Application from Kustomization:
If you select Helm repository as the source type, you will be able to add Application from HelmRelease.
And if you choose the profiles Helm chart repository URL, you can select a profile from our Profiles list.
Finally, you can create a pull request to your target cluster and see it on your GitOps repository.
"},{"location":"cluster-management/#follow-our-user-guide","title":"Follow Our User Guide","text":"Our user guide provides two pathways to deployment:
Just click the option you want to get started with, and let's go.
"},{"location":"cluster-management/cluster-management-troubleshooting/","title":"Cluster Management Troubleshooting ENTERPRISE","text":"We'll use this page to help you move past common troublesome situations.
"},{"location":"cluster-management/cluster-management-troubleshooting/#git-repositories-and-resources","title":"Git Repositories and Resources","text":"To authenticate using Git during the pull request creation, you will need to select the Git repository where you'll create the pull request.
Depending on the action performed on the resource (creation/deletion/editing), the default Git repository selected in the UI is determined in the following order:
In the case of deletion and editing, if the resource repository is found amongst the Git repositories that the user has access to, it will be preselected and the selection will be disabled. If it is not found, you can choose a new repository.
In the case of tenants, we recommend adding the weave.works/repo-role: default to an appropriate Git repository.
The system will try and automatically calculate the correct HTTPS API endpoint to create a pull request against. For example, if the Git repository URL is ssh://git@github.com/org/repo.git, the system will try and convert it to https://github.com/org/repo.git.
However, it is not always possible to accurately derive this URL. An override can be specified to set the correct URL instead. For example, the SSH URL may be ssh://git@interal-ssh-server:2222/org/repo.git and the correct HTTPS URL may be https://gitlab.example.com/org/repo.git.
In this case, we set the override via the weave.works/repo-https-url annotation on the GitRepository object:
apiVersion: source.toolkit.fluxcd.io/v1beta1\nkind: GitRepository\nmetadata:\nname: repo\nnamespace: flux-system\nannotations:\n// highlight-start\nweave.works/repo-https-url: https://gitlab.example.com/org/repo.git\n// highlight-end\nspec:\ninterval: 1m\nurl: ssh://git@interal-ssh-server:2222/org/repo.git\nThe pull request will then be created against the correct HTTPS API.
The above also applies to application creation.
"},{"location":"cluster-management/deploying-capa-eks/","title":"Deploying CAPA with EKS ENTERPRISE","text":"Weave GitOps Enterprise can leverage Cluster API providers to enable leaf cluster creation. Cluster API provides declarative APIs, controllers, and tooling to manage the lifecycle of Kubernetes clusters across a large number of infrastructure providers. Cluster API custom resource definitions (CRDs) are platform-independent as each provider implementation handles the creation of virtual machines, VPCs, networks, and other required infrastructure parts\u2014enabling consistent and repeatable cluster deployments.
As an AWS advanced technology partner, Weaveworks has been working tirelessly to ensure that deploying EKS anywhere is smooth and removes the barriers to application modernization.
"},{"location":"cluster-management/deploying-capa-eks/#prerequisites","title":"Prerequisites","text":"You'll need to install the following software before continuing with these instructions:
Some Cluster API providers allow you to choose the account or identity that the new cluster will be created with. This is often referred to as Multi-tenancy in the CAPI world. Weave GitOps currently supports:
When a cluster is provisioned, by default it will reconcile all the manifests in ./clusters/<cluster-namespace>/<cluster-name> and ./clusters/bases.
To display Applications and Sources in the UI we need to give the logged in user permissions to inspect the new cluster.
Adding common RBAC rules to ./clusters/bases/rbac is an easy way to configure this!
import WegoAdmin from \"!!raw-loader!./assets/rbac/wego-admin.yaml\";
curl -o clusters/bases/rbac/wego-admin.yaml https://docs.gitops.weave.works/assets/files/wego-admin-c80945c1acf9908fe6e61139ef65c62e.yaml\n\n<CodeBlock title=\"clusters/bases/rbac/wego-admin.yaml\" className=\"language-yaml\"
{WegoAdmin}
"},{"location":"cluster-management/deploying-capa-eks/#2-build-a-kubernetes-platform-with-built-in-components-preconfigured-for-your-organization","title":"2. Build a Kubernetes Platform with Built-in Components Preconfigured for Your Organization","text":"To do this, go to Weaveworks' Profiles Catalog.
See CAPI Templates page for more details on this topic. Once we load a template we can use it in the UI to create clusters!
import CapaTemplate from \"!!raw-loader!./assets/templates/capa-template.yaml\";
Download the template below to your config repository path, then commit and push to your Git origin.
curl -o clusters/management/capi/templates/capa-template.yaml https://docs.gitops.weave.works/assets/files/capa-template-49001fbae51e2a9f365b80caebd6f341.yaml\n {% include '/assets/templates/capa-template.yaml' %}\n<CodeBlock title=\"clusters/management/apps/capi/templates/capa-template.yaml\" className=\"language-yaml\"
{CapaTemplate}
"},{"location":"cluster-management/deploying-capa-eks/#3-add-a-cluster-bootstrap-config","title":"3. Add a Cluster Bootstrap Config","text":"This step ensures that Flux gets installed into your cluster.\u00a0Create a cluster bootstrap config as follows:
kubectl create secret generic my-pat --from-literal GITHUB_TOKEN=$GITHUB_TOKEN\nimport CapiGitopsCDC from \"!!raw-loader!./assets/bootstrap/capi-gitops-cluster-bootstrap-config.yaml\";
Download the config with:
curl -o clusters/management/capi/bootstrap/capi-gitops-cluster-bootstrap-config.yaml https://docs.gitops.weave.works/assets/files/capi-gitops-cluster-bootstrap-config-d9934a1e6872a5b7ee5559d2d97a3d83.yaml\nThen update the GITOPS_REPO variable to point to your cluster
\n<CodeBlock title=\"clusters/management/capi/boostrap/capi-gitops-cluster-bootstrap-config.yaml\" className=\"language-yaml\"
{CapiGitopsCDC}
"},{"location":"cluster-management/deploying-capa-eks/#4-delete-a-cluster-with-the-weave-gitops-enterprise-ui","title":"4. Delete a Cluster with the Weave GitOps Enterprise UI","text":"Here are the steps:
Note that you can't apply an empty repository to a cluster. If you have Cluster API clusters and other manifests committed to this repository, and then delete all of them so there are zero manifests left, then the apply will fail and the resources will not be removed from the cluster. A workaround is to add a dummy ConfigMap back to the Git repository after deleting everything else so that there is at least one manifest to apply.
"},{"location":"cluster-management/deploying-capa-eks/#5-disable-capi-support","title":"5. Disable CAPI Support","text":"If you do not need CAPI-based cluster management support, you can disable CAPI via the Helm Chart values.
Update your Weave GitOps Enterprise HelmRelease object with the global.capiEnabled value set to false:
---\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: HelmRepository\nmetadata:\nname: weave-gitops-enterprise-charts\nnamespace: flux-system\nspec:\ninterval: 60m\nsecretRef:\nname: weave-gitops-enterprise-credentials\nurl: https://charts.dev.wkp.weave.works/releases/charts-v3\n---\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: weave-gitops-enterprise\nnamespace: flux-system\nspec:\nchart:\nspec:\ninterval: 65m\nchart: mccp\nsourceRef:\nkind: HelmRepository\nname: weave-gitops-enterprise-charts\nnamespace: flux-system\nversion: 0.12.0\ninstall:\ncrds: CreateReplace\nupgrade:\ncrds: CreateReplace\ninterval: 50m\nvalues:\nglobal:\ncapiEnabled: false\nAnd that's it!
"},{"location":"cluster-management/managing-clusters-without-capi/","title":"Managing Clusters Without Cluster API","text":"import CodeBlock from \"@theme/CodeBlock\"; import BrowserOnly from \"@docusaurus/BrowserOnly\";
"},{"location":"cluster-management/managing-clusters-without-capi/#managing-clusters-without-cluster-api-enterprise","title":"Managing Clusters Without Cluster API ENTERPRISE","text":"You do not need Cluster API to add your Kubernetes cluster to Weave GitOps Enterprise. The only thing you need is a secret containing a valid kubeconfig.
Here's how to create a kubeconfig secret.
apiVersion: v1\nkind: ServiceAccount\nmetadata:\nname: demo-01\nnamespace: default\n ---\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRoleBinding\nmetadata:\nname: impersonate-user-groups\nsubjects:\n- kind: ServiceAccount\nname: wgesa\nnamespace: default\nroleRef:\nkind: ClusterRole\nname: user-groups-impersonator\napiGroup: rbac.authorization.k8s.io\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRole\nmetadata:\nname: user-groups-impersonator\nrules:\n- apiGroups: [\"\"]\nresources: [\"users\", \"groups\"]\nverbs: [\"impersonate\"]\n- apiGroups: [\"\"]\nresources: [\"namespaces\"]\nverbs: [\"get\", \"list\"]\nThis will allow WGE to introspect the cluster for available namespaces.
Once we know what namespaces are available we can test whether the logged in user can access them via impersonation.
kubectl get secrets --field-selector type=kubernetes.io/service-account-token\n NAME TYPE DATA AGE\n default-token-lsjz4 kubernetes.io/service-account-token 3 13d\n demo-01-token-gqz7p kubernetes.io/service-account-token 3 99m\n(demo-01-token-gqz7p is the secret that holds the token for demo-01 service account.)
Then, run the following command to get the service account token:
TOKEN=$(kubectl get secret demo-01-token-gqz7p -o jsonpath={.data.token} | base64 -d)\n #!/bin/bash\nif [[ -z \"$CLUSTER_NAME\" ]]; then\necho \"Ensure CLUSTER_NAME has been set\"\nexit 1\nfi\nif [[ -z \"$CA_CERTIFICATE\" ]]; then\necho \"Ensure CA_CERTIFICATE has been set to the path of the CA certificate\"\nexit 1\nfi\nif [[ -z \"$ENDPOINT\" ]]; then\necho \"Ensure ENDPOINT has been set\"\nexit 1\nfi\nif [[ -z \"$TOKEN\" ]]; then\necho \"Ensure TOKEN has been set\"\nexit 1\nfi\nexport CLUSTER_CA_CERTIFICATE=$(cat \"$CA_CERTIFICATE\" | base64)\nenvsubst <<EOF\n apiVersion: v1\n kind: Config\n clusters:\n - name: $CLUSTER_NAME\n cluster:\n server: https://$ENDPOINT\n certificate-authority-data: $CLUSTER_CA_CERTIFICATE\n users:\n - name: $CLUSTER_NAME\n user:\n token: $TOKEN\n contexts:\n - name: $CLUSTER_NAME\n context:\n cluster: $CLUSTER_NAME\n user: $CLUSTER_NAME\n current-context: $CLUSTER_NAME\n EOF\nYou'll need to copy the contents of the certificate into the ca.crt file used below.
CLUSTER_NAME=demo-01 \\\nCA_CERTIFICATE=ca.crt \\\nENDPOINT=<control-plane-ip-address> \\\nTOKEN=<token> ./static-kubeconfig.sh > demo-01-kubeconfig\nkubectl create secret generic demo-01-kubeconfig \\\n--from-file=value=./demo-01-kubeconfig\nIf you already have a kubeconfig stored in a secret in your management cluster, continue with the \"Create a GitopsCluster\" step below.
If you have a kubeconfig, but it is not yet stored in your management cluster, load it into the cluster using this command:
kubectl create secret generic demo-01-kubeconfig \\\n--from-file=value=./demo-01-kubeconfig\nThis step ensures that Flux gets installed into your cluster.\u00a0Create a cluster bootstrap config as follows:
kubectl create secret generic my-pat --from-literal GITHUB_TOKEN=$GITHUB_TOKEN\nimport CapiGitopsCDC from \"!!raw-loader!./assets/bootstrap/capi-gitops-cluster-bootstrap-config.yaml\";
Download the config with:
{() => ( curl -o clusters/management/capi/bootstrap/capi-gitops-cluster-bootstrap-config.yaml{\" \"} {window.location.protocol} //{window.location.host} { require(\"./assets/bootstrap/capi-gitops-cluster-bootstrap-config.yaml\") .default } )}
Then update the GITHUB_USER variable to point to your repository
<CodeBlock title=\"clusters/management/capi/boostrap/capi-gitops-cluster-bootstrap-config.yaml\" className=\"language-yaml\"
{CapiGitopsCDC}
"},{"location":"cluster-management/managing-clusters-without-capi/#connect-a-cluster","title":"Connect a Cluster","text":"To connect your cluster, you need to add some common RBAC rules into the clusters/bases folder. When a cluster is provisioned, by default it will reconcile all the manifests in ./clusters/<cluster-namespace>/<cluster-name> and ./clusters/bases.
To display Applications and Sources in the UI, we need to give the logged-in user the permission to inspect the new cluster. Adding common RBAC rules to ./clusters/bases/rbac is an easy way to configure this.
import WegoAdmin from \"!!raw-loader!./assets/rbac/wego-admin.yaml\";
{() => ( curl -o clusters/bases/rbac/wego-admin.yaml {window.location.protocol}// {window.location.host} {require(\"./assets/rbac/wego-admin.yaml\").default} )}
Expand to see full template yaml<CodeBlock title=\"clusters/bases/rbac/wego-admin.yaml\" className=\"language-yaml\"
{WegoAdmin}
"},{"location":"cluster-management/managing-clusters-without-capi/#create-a-gitopscluster","title":"Create aGitopsCluster","text":"When a GitopsCluster appears in the cluster, the Cluster Bootstrap Controller will install Flux on it and by default start reconciling the ./clusters/demo-01 path in your management cluster's Git repository:
apiVersion: gitops.weave.works/v1alpha1\nkind: GitopsCluster\nmetadata:\nname: demo-01\nnamespace: default\n# Signals that this cluster should be bootstrapped.\nlabels:\nweave.works/capi: bootstrap\nspec:\nsecretRef:\nname: demo-01-kubeconfig\nTo use the Weave GitOps Enterprise user interface (UI) to inspect the Applications and Sources running on the new cluster, you'll need permissions. We took care of this above when we stored your RBAC rules in ./clusters/bases. In the following step, we'll create a kustomization to add these common resources onto our new cluster:
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2\nkind: Kustomization\nmetadata:\ncreationTimestamp: null\nname: clusters-bases-kustomization\nnamespace: flux-system\nspec:\ninterval: 10m0s\npath: clusters/bases\nprune: true\nsourceRef:\nkind: GitRepository\nname: flux-system\nSave these two files in your Git repository, then commit and push.
Once Flux has reconciled the cluster, you can inspect your Flux resources via the UI!
"},{"location":"cluster-management/managing-clusters-without-capi/#debugging-tip-checking-that-your-kubeconfig-secret-is-in-your-cluster","title":"Debugging Tip: Checking that Your kubeconfig Secret Is in Your Cluster","text":"To test that your kubeconfig secret is correctly set up, apply the following manifest and check the logs after the job completes:
Expand to see manifest ---\napiVersion: batch/v1\nkind: Job\nmetadata:\nname: kubectl\nspec:\nttlSecondsAfterFinished: 30\ntemplate:\nspec:\ncontainers:\n- name: kubectl\nimage: bitnami/kubectl\nargs:\n[\n\"get\",\n\"pods\",\n\"-n\",\n\"kube-system\",\n\"--kubeconfig\",\n\"/etc/kubeconfig/value\",\n]\nvolumeMounts:\n- name: kubeconfig\nmountPath: \"/etc/kubeconfig\"\nreadOnly: true\nrestartPolicy: Never\nvolumes:\n- name: kubeconfig\nsecret:\nsecretName: demo-01-kubeconfig\noptional: false\nIn the manifest above, demo-01-kubeconfig is the name of the secret that contains the kubeconfig for the remote cluster.
Other documentation that you might find useful:
BEFORE YOU START
The following instructions require you to make minor changes to the content of your own hosted Helm repository.
To put it simply, Profiles are Helm charts. To create a Profile, you need to add an annotation to a Helm chart.
A very simple Helm chart marked up as a Profile looks like this:
name: demo-profile\nversion: 0.0.1\nannotations:\nweave.works/profile: \"A Demo Profile\"\nAlternatively, you can annotate a Flux HelmRepository
apiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: HelmRepository\nmetadata:\nname: podinfo\nnamespace: default\nannotations:\nweave.works/profiles: \"true\" # this identifies all charts as profiles\nspec:\ninterval: 5m0s\nurl: https://stefanprodan.github.io/podinfo\nThis will ensure that all charts in the HelmRepository are identified as Profiles.
Profile layers are a mechanism for loosely defining dependencies between Profiles.
To add a layer to a Profile chart:
name: demo-profile\nversion: 0.0.1\nannotations:\nweave.works/profile: \"A Demo Profile\"\nweave.works/layer: \"demo\"\nWhen multiple Profiles are specified in an API call, with layers in the API request then the set of layers is sorted, reversed, and configured as dependencies using Flux's dependsOn mechanism.
\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 \u2502 \u2502 \u2502 \u2502 \u2502\n\u2502 layer-3 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u25ba layer-2 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u25ba layer-1 \u2502\n\u2502 \u2502 \u2502 \u2502 \u2502 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n dependsOn dependsOn\nThe scope of the dependsOn calculation is limited to the set of Profiles in the API call.
If only one chart is being installed, no dependsOn is configured.
If several charts are installed in the same layer, then the preceeding layer charts will be configured to depend on all the charts in the succeeding layer.
\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 \u2502 \u2502 \u2502 \u2502 \u2502\n\u2502 layer-3 \u251c\u2500\u2500\u2500\u2500\u2500\u25ba layer-2 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u25ba layer-1 \u2502\n\u2502 \u2502 \u2502 \u2502 \u2502 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u25b2\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n dependsOn \u2502 dependsOn \u2502\n \u2502 \u2502\n \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n \u2502 \u2502 \u2502 \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u25ba layer-2 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502 \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n dependsOn\ndependsOn for the chart without a layer to depend on the chart with layer."},{"location":"cluster-management/profiles/#optional-use-a-helm-chart-from-a-remote-publicprivate-repository","title":"(Optional) Use a Helm Chart from a Remote Public/Private Repository","text":"You can add your Profiles to a remote repository that can be referenced using a HelmRepository resource. The repository can be either public or private. Using a private repo requires a few extra steps.
In this example, a public repo and branch is referenced directly where the Helm releases are: HelmRepository.yaml
apiVersion: source.toolkit.fluxcd.io/v1beta1\nkind: HelmRepository\nmetadata:\nname: weaveworks-charts\nnamespace: flux-system\nspec:\ninterval: 1m\nurl: https://weaveworks.github.io/weave-gitops-profile-examples/\nTo use private repositories with restricted access, you can use a secret synced to the target leaf cluster. SecretSync references the secret as spec.secretRef. The labels of your target leaf cluster are added for the syncer to match clusters against those labels using spec.clusterSelector.matchLabels.
apiVersion: capi.weave.works/v1alpha1\nkind: SecretSync\nmetadata:\nname: my-dev-secret-syncer\nnamespace: flux-system\nspec:\nclusterSelector:\nmatchLabels:\nweave.works/capi: bootstrap\nsecretRef:\nname: weave-gitops-enterprise-credentials\ntargetNamespace: flux-system\nOnce the SecretSync and Secret are available, the secret can be directly referenced in the HelmRepository object:
PrivateHelmRepository.yamlapiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: HelmRepository\nmetadata:\nname: weaveworks-charts\nnamespace: flux-system\nspec:\ninterval: 60m\nsecretRef:\nname: weave-gitops-enterprise-credentials\nurl: https://charts.dev.wkp.weave.works/releases/charts-v3\nNote: The HelmRepoSecret, SecretSync, and the GitopsCluster should all be in the same namespace.
WGE inspects the namespace in the management cluster where it is deployed, and looks for a HelmRepository object named weaveworks-charts. This Kubernetes object should point to a Helm chart repository that includes the Profiles available for installation.
When creating a cluster from the UI using a CAPI template, these Profiles are available for selection in the Profiles section of the template. For example:
As shown above, some Profiles are optional, while others are required. This is determined when the template is authored and allows for operations teams to control which Helm packages should be installed on new clusters by default.
To enable editing of the yaml values for required Profiles, add the editable flag in the annotation and describe the required Profile in the template. For example:
apiVersion: templates.weave.works/v1alpha2\nkind: GitOpsTemplate\nmetadata:\nname: connect-a-cluster-with-policies\nnamespace: default\nannotations:\ncapi.weave.works/profile-0: '{\"name\": \"weave-policy-agent\", \"editable\": true, \"version\": \"0.2.8\", \"values\": \"accountId: weaveworks\\nclusterId: ${CLUSTER_NAME}\" }'\nWeave GitOps templates describe the properties of your cluster\u2014how many nodes, what version of Kubernetes, etc. The identity refers to which account will be used to create the cluster. When you render a template, you may want to set the credentials to be used for this cluster\u2014for example, if the cost is allocated to a specific team.
The rendered resource can be automatically configured with the selected credentials.
Credentials are injected into the following resources: * AWSCluster, AWSManagedControlPlane * AzureCluster, AzureManagedCluster * VSphereCluster
If no credentials are selected, no changes will be applied, and the credentials used by your CAPI controller will be used as the default.
In our cluster we have the template:
apiVersion: templates.weave.works/v1alpha2\nkind: GitOpsTemplate\nmetadata:\nname: capa-cluster-template\nspec:\nresourcetemplates:\n- contents:\n- apiVersion: infrastructure.cluster.x-k8s.io/v1alpha4\nkind: AWSCluster\nmetadata:\nname: \"${CLUSTER_NAME}\"\nspec:\nregion: \"${AWS_REGION}\"\nand the identity
apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3\nkind: AWSClusterStaticIdentity\nmetadata:\nname: \"test-account\"\nspec:\nsecretRef:\nname: test-account-creds\nnamespace: capa-system\nallowedNamespaces:\nselector:\nmatchLabels:\ncluster.x-k8s.io/ns: \"testlabel\"\nWe can select Weave GitOps to use the test-account when creating the cluster by using the Infrastructure provider credentials dropdown on the Create new cluster with template page:
The resulting definition will have the identity injected into the appropriate place in the template, for this example:
apiVersion: infrastructure.cluster.x-k8s.io/v1alpha4\nkind: AWSCluster\nmetadata:\nname: example-cluster\nspec:\nregion: eu-north-1\nidentityRef:\nkind: AWSClusterStaticIdentity\nname: test-account\nidentityRefs","text":"The supported providers implement multi-tenancy by setting an identityRef on the the provider cluster object, e.g. AWSCluster, AzureCluster or VSphereCluster.
Weave GitOps will search all namespaces in the cluster for potential identities that can be used to create a cluster. The following identity kinds are currently supported and their corresponding Cluster kinds:
Ready for more GitOps?
To purchase an entitlement to Weave GitOps Enterprise, please contact sales@weave.works.
Weave GitOps Enterprise provides ops teams with an easy way to assess the health of multiple clusters in a single place. It shows cluster information such as Kubernetes version and number of nodes and provides details about the GitOps operations on those clusters, such as Git repositories and recent commits. Additionally, it aggregates Prometheus alerts to assist with troubleshooting.
If you have already purchased your entitlement, head to the installation page.
"},{"location":"enterprise/#feature-breakdown","title":"Feature Breakdown","text":"In addition to the features in the OSS edition, Weave GitOps Enterprise offers the following capabilities, taking your delivery from simple Continuous Delivery to Internal Developer Platform:
"},{"location":"enterprise/#cluster-fleet-management","title":"Cluster Fleet Management","text":"Weave GitOps Enterprise (WGE) simplifies cluster lifecycle management at scale\u2014even massive scale. Through pull requests, which make every action recorded and auditable, WGE makes it possible for teams to create, update, and delete clusters across entire fleets. WGE further simplifies the process by providing both a user interface (UI) and a command line interface (CLI) for teams to interact with and manage clusters on-prem, across clouds, and in hybrid environments. WGE works with Terraform, Crossplane, and any Cluster API provider.
"},{"location":"enterprise/#trusted-application-delivery","title":"Trusted Application Delivery","text":"Add policy as code to GitOps pipelines and enforce security and compliance, application resilience and coding standards from source to production. Validate policy conformance at every step in the software delivery pipeline: commit, build, deploy and run time.
"},{"location":"enterprise/#progressive-delivery","title":"Progressive Delivery","text":"Deploy into production environments safely using canary, blue/green deployment, and A/B strategies. Simple, single-file configuration defines success rollback. Measure Service Level Objectives (SLOs) using observability metrics from Prometheus, Datadog, New Relic, and others.
"},{"location":"enterprise/#cd-pipelines","title":"CD Pipelines","text":"Rollout new software from development to production. Environment rollouts that work with your existing CI system.
"},{"location":"enterprise/#team-workspaces","title":"Team Workspaces","text":"Allow DevOps teams to work seamlessly together with multi-tenancy, total RBAC control, and policy enforcement, with integration to enterprise IAM.
"},{"location":"enterprise/#self-service-templates-and-profiles","title":"Self-Service Templates and Profiles","text":"Component profiles enable teams to deploy standard services quickly, consistently and reliably. Teams can curate the profiles that are available within their estate ensuring there is consistency everywhere. Using GitOps it's easy to guarantee the latest, secure versions of any component are deployed in all production systems.
"},{"location":"enterprise/#health-status-and-compliance-dashboards","title":"Health Status and Compliance Dashboards","text":"Gain a single view of the health and state of the cluster and its workloads. Monitor deployments and alert on policy violations across apps and clusters.
"},{"location":"enterprise/#kubernetes-anywhere","title":"Kubernetes Anywhere","text":"Reduce complexity with GitOps and install across all major target environments including support for on-premise, edge, hybrid, and multi-cloud Kubernetes clusters.
"},{"location":"enterprise/#critical-247-support","title":"Critical 24/7 Support","text":"Your business and workloads operate around the clock, and so do we. Whenever you have a problem, our experts are there to help. We\u2019ve got your back!
"},{"location":"enterprise/install-enterprise-airgap/","title":"Install Enterprise in Air-gapped Environments ENTERPRISE","text":"From wikipedia
An air gap, air wall, air gapping or disconnected network is a network security measure employed on one or more computers to ensure that a secure computer network is physically isolated from unsecured networks, such as the public Internet or an unsecured local area network...
This document guides on how to install Weave GitOps Enterprise (WGE) in a restricted environment.
"},{"location":"enterprise/install-enterprise-airgap/#before-you-start","title":"Before You Start","text":"There are multiple restrictions that could happen within an air-gapped environment. This guide assumes that you have egress network restrictions. In order to install WGE, the required artifacts must be loaded from a private registry. This guide helps you with the task to identity the Helm charts and container images required to install WGE and to load them into your private registry.
It also assumes that you could prepare the installation from a proxy host. A proxy host is defined here as a computer that is able to access to both the public and private network. It could take different shapes, for example, it could be a bastion host, a corp laptop, etc.
Access to both public and private network is required during the airgap installation but not simultaneously. It is expected to have an online stage to gather the artifacts first, and an offline stage later, to load the artifacts in the private network.
Finally, we aim to provide an end to end example to use it as a guidance more than a recipe. Feel free to adapt the details that do not fit within your context.
"},{"location":"enterprise/install-enterprise-airgap/#install-wge","title":"Install WGE","text":"There are different variations of the following stages and conditions. We consider that installing WGE in an air-gapped environment could follow the following stages.
The main goal of this stage is to recreate a local WGE within your context, to collect the container images and Helm charts, that will be required in your private registry for the offline installation.
A three-step setup is followed.
There are many possible configurations for this host. This guide will assume that the host has installed the following:
Create a kind cluster with registry following this guide
"},{"location":"enterprise/install-enterprise-airgap/#install-flux","title":"Install Flux","text":"You could just use flux install to install Flux into your kind cluster
We are going to install ChartMuseum via Flux.
Remember to also install helm plugin cm-push.
Expand to see installation yaml---\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: HelmRepository\nmetadata:\nname: chartmuseum\nnamespace: flux-system\nspec:\ninterval: 10m\nurl: https://chartmuseum.github.io/charts\n---\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: chartmuseum\nnamespace: flux-system\nspec:\nchart:\nspec:\nchart: chartmuseum\nsourceRef:\nkind: HelmRepository\nname: chartmuseum\nnamespace: flux-system\ninterval: 10m0s\ntimeout: 10m0s\nreleaseName: helm-repo\ninstall:\ncrds: CreateReplace\nremediation:\nretries: 3\nvalues:\nenv:\nopen:\nDISABLE_API: \"false\"\nAUTH_ANONYMOUS_GET: \"true\"\nSet up access from your host.
#expose kubernetes svc\nkubectl -n flux-system port-forward svc/helm-repo-chartmuseum 8080:8080 &\n\n#add hostname\nsudo -- sh -c \"echo 127.0.0.1 helm-repo-chartmuseum >> /etc/hosts\"\n#add repo to helm\nhelm repo add private http://helm-repo-chartmuseum:8080\n\n#test that works\nhelm repo update private\nAt this stage you have already a private registry for container images and helm charts.
"},{"location":"enterprise/install-enterprise-airgap/#install-wge_1","title":"Install WGE","text":"This step is to gather the artifacts and images in your local environment to push to the private registry.
"},{"location":"enterprise/install-enterprise-airgap/#cluster-api","title":"Cluster API","text":"This would vary depending on the provider, given that we target a offline environment, most likely we are in a private cloud environment, so we will be using liquidmetal.
Export these environment variables to configure your CAPI experience. Adjust them to your context.
export CAPI_BASE_PATH=/tmp/capi\nexport CERT_MANAGER_VERSION=v1.9.1\nexport CAPI_VERSION=v1.3.0\nexport CAPMVM_VERSION=v0.7.0\nexport EXP_CLUSTER_RESOURCE_SET=true\nexport CONTROL_PLANE_MACHINE_COUNT=1\nexport WORKER_MACHINE_COUNT=1\nexport CONTROL_PLANE_VIP=\"192.168.100.9\"\nexport HOST_ENDPOINT=\"192.168.1.130:9090\"\nExecute the following script to generate clusterctl config file.
cat << EOF > clusterctl.yaml\ncert-manager:\n url: \"$CAPI_BASE_PATH/cert-manager/$CERT_MANAGER_VERSION/cert-manager.yaml\"\n\nproviders:\n - name: \"microvm\"\n url: \"$CAPI_BASE_PATH/infrastructure-microvm/$CAPMVM_VERSION/infrastructure-components.yaml\"\n type: \"InfrastructureProvider\"\n - name: \"cluster-api\"\n url: \"$CAPI_BASE_PATH/cluster-api/$CAPI_VERSION/core-components.yaml\"\n type: \"CoreProvider\"\n - name: \"kubeadm\"\n url: \"$CAPI_BASE_PATH/bootstrap-kubeadm/$CAPI_VERSION/bootstrap-components.yaml\"\n type: \"BootstrapProvider\"\n - name: \"kubeadm\"\n url: \"$CAPI_BASE_PATH/control-plane-kubeadm/$CAPI_VERSION/control-plane-components.yaml\"\n type: \"ControlPlaneProvider\"\nEOF\nmake using the following makefile to intialise CAPI in your cluster: Expand to see Makefile contents .PHONY := capi\n\ncapi: capi-init capi-cluster\n\ncapi-init: cert-manager cluster-api bootstrap-kubeadm control-plane-kubeadm microvm clusterctl-init\n\ncert-manager:\nmkdir -p $(CAPI_BASE_PATH)/cert-manager/$(CERT_MANAGER_VERSION)\ncurl -L https://github.com/cert-manager/cert-manager/releases/download/$(CERT_MANAGER_VERSION)/cert-manager.yaml --output $(CAPI_BASE_PATH)/cert-manager/$(CERT_MANAGER_VERSION)/cert-manager.yaml\n\ncluster-api:\nmkdir -p $(CAPI_BASE_PATH)/cluster-api/$(CAPI_VERSION)\ncurl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/$(CAPI_VERSION)/core-components.yaml --output $(CAPI_BASE_PATH)/cluster-api/$(CAPI_VERSION)/core-components.yaml\n curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/$(CAPI_VERSION)/metadata.yaml --output $(CAPI_BASE_PATH)/cluster-api/$(CAPI_VERSION)/metadata.yaml\n\nbootstrap-kubeadm:\nmkdir -p $(CAPI_BASE_PATH)/bootstrap-kubeadm/$(CAPI_VERSION)\ncurl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/$(CAPI_VERSION)/bootstrap-components.yaml --output $(CAPI_BASE_PATH)/bootstrap-kubeadm/$(CAPI_VERSION)/bootstrap-components.yaml\n curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/$(CAPI_VERSION)/metadata.yaml --output $(CAPI_BASE_PATH)/bootstrap-kubeadm/$(CAPI_VERSION)/metadata.yaml\n\ncontrol-plane-kubeadm:\nmkdir -p $(CAPI_BASE_PATH)/control-plane-kubeadm/$(CAPI_VERSION)\ncurl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/$(CAPI_VERSION)/control-plane-components.yaml --output $(CAPI_BASE_PATH)/control-plane-kubeadm/$(CAPI_VERSION)/control-plane-components.yaml\n curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/$(CAPI_VERSION)/metadata.yaml --output $(CAPI_BASE_PATH)/control-plane-kubeadm/$(CAPI_VERSION)/metadata.yaml\n\nmicrovm:\nmkdir -p $(CAPI_BASE_PATH)/infrastructure-microvm/$(CAPMVM_VERSION)\ncurl -L https://github.com/weaveworks-liquidmetal/cluster-api-provider-microvm/releases/download/$(CAPMVM_VERSION)/infrastructure-components.yaml --output $(CAPI_BASE_PATH)/infrastructure-microvm/$(CAPMVM_VERSION)/infrastructure-components.yaml\n curl -L https://github.com/weaveworks-liquidmetal/cluster-api-provider-microvm/releases/download/$(CAPMVM_VERSION)/cluster-template-cilium.yaml --output $(CAPI_BASE_PATH)/infrastructure-microvm/$(CAPMVM_VERSION)/cluster-template-cilium.yaml\n curl -L https://github.com/weaveworks-liquidmetal/cluster-api-provider-microvm/releases/download/$(CAPMVM_VERSION)/metadata.yaml --output $(CAPI_BASE_PATH)/infrastructure-microvm/$(CAPMVM_VERSION)/metadata.yaml\n\nclusterctl-init:\nclusterctl init --wait-providers -v 4 --config clusterctl.yaml --infrastructure microvm\n\ncapi-cluster:\nclusterctl generate cluster --config clusterctl.yaml -i microvm:$(CAPMVM_VERSION) -f cilium lm-demo | kubectl apply -f -\nApply the following example manifest to deploy the Terraform Controller:
Expand to see file contentsapiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: HelmRepository\nmetadata:\nname: tf-controller\nnamespace: flux-system\nspec:\ninterval: 10m\nurl: https://weaveworks.github.io/tf-controller/\n---\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: tf-controller\nnamespace: flux-system\nspec:\nchart:\nspec:\nchart: tf-controller\nversion: \"0.9.2\"\nsourceRef:\nkind: HelmRepository\nname: tf-controller\nnamespace: flux-system\ninterval: 10m0s\ninstall:\ncrds: CreateReplace\nremediation:\nretries: 3\nupgrade:\ncrds: CreateReplace\nUpdate the following manifest to your context.
Expand to see file contents---\napiVersion: v1\ndata:\ndeploy-key: <changeme>\nentitlement: <changeme>\npassword: <changeme>\nusername: <changeme>\nkind: Secret\nmetadata:\nlabels:\nkustomize.toolkit.fluxcd.io/name: shared-secrets\nkustomize.toolkit.fluxcd.io/namespace: flux-system\nname: weave-gitops-enterprise-credentials\nnamespace: flux-system\ntype: Opaque\n---\napiVersion: v1\ndata:\npassword: <changeme>\nusername: <changeme>\nkind: Secret\nmetadata:\nlabels:\nkustomize.toolkit.fluxcd.io/name: enterprise\nkustomize.toolkit.fluxcd.io/namespace: flux-system\nname: cluster-user-auth\nnamespace: flux-system\ntype: Opaque\n---\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: HelmRepository\nmetadata:\nname: weave-gitops-enterprise-charts\nnamespace: flux-system\nspec:\ninterval: 10m\nsecretRef:\nname: weave-gitops-enterprise-credentials\nurl: https://charts.dev.wkp.weave.works/releases/charts-v3\n---\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: weave-gitops-enterprise\nnamespace: flux-system\nspec:\nchart:\nspec:\nchart: mccp\nversion: \"0.10.2\"\nsourceRef:\nkind: HelmRepository\nname: weave-gitops-enterprise-charts\nnamespace: flux-system\ninterval: 10m0s\ninstall:\ncrds: CreateReplace\nremediation:\nretries: 3\nupgrade:\ncrds: CreateReplace\nvalues:\nglobal:\ncapiEnabled: true\nenablePipelines: true\nenableTerraformUI: true\nclusterBootstrapController:\nenabled: true\ncluster-controller:\ncontrollerManager:\nkubeRbacProxy:\nimage:\nrepository: gcr.io/kubebuilder/kube-rbac-proxy\ntag: v0.8.0\nmanager:\nimage:\nrepository: docker.io/weaveworks/cluster-controller\ntag: v1.4.1\npolicy-agent:\nenabled: true\nimage: weaveworks/policy-agent\npipeline-controller:\ncontroller:\nmanager:\nimage:\nrepository: ghcr.io/weaveworks/pipeline-controller\nimages:\nclustersService: docker.io/weaveworks/weave-gitops-enterprise-clusters-service:v0.10.2\nuiServer: docker.io/weaveworks/weave-gitops-enterprise-ui-server:v0.10.2\nclusterBootstrapController: weaveworks/cluster-bootstrap-controller:v0.4.0\nAt this stage you should have a local management cluster with Weave GitOps Enterprise installed.
\u279c kubectl get pods -A\nNAMESPACE NAME READY STATUS RESTARTS AGE\n...\nflux-system weave-gitops-enterprise-cluster-controller-6f8c69dc8-tq994 2/2 Running 5 (12h ago) 13h\nflux-system weave-gitops-enterprise-mccp-cluster-bootstrap-controller-cxd9c 2/2 Running 0 13h\nflux-system weave-gitops-enterprise-mccp-cluster-service-8485f5f956-pdtxw 1/1 Running 0 12h\nflux-system weave-gitops-enterprise-pipeline-controller-85b76d95bd-2sw7v 1/1 Running 0 13h\n...\nYou can observe the installed Helm Charts with kubectl:
kubectl get helmcharts.source.toolkit.fluxcd.io\nNAME CHART VERSION SOURCE KIND SOURCE NAME AGE READY STATUS\nflux-system-cert-manager cert-manager 0.0.7 HelmRepository weaveworks-charts 13h True pulled 'cert-manager' chart with version '0.0.7'\nflux-system-tf-controller tf-controller 0.9.2 HelmRepository tf-controller 13h True pulled 'tf-controller' chart with version '0.9.2'\nflux-system-weave-gitops-enterprise mccp v0.10.2 HelmRepository weave-gitops-enterprise-charts 13h True pulled 'mccp' chart with version '0.10.2'\nAs well as the container images:
kubectl get pods --all-namespaces -o jsonpath=\"{.items[*].spec['containers','initContainers'][*].image}\" |tr -s '[[:space:]]' '\\n' \\\n| sort | uniq | grep -vE 'kindest|etcd|coredns'\n\ndocker.io/prom/prometheus:v2.34.0\ndocker.io/weaveworks/cluster-controller:v1.4.1\ndocker.io/weaveworks/weave-gitops-enterprise-clusters-service:v0.10.2\ndocker.io/weaveworks/weave-gitops-enterprise-ui-server:v0.10.2\nghcr.io/fluxcd/flagger-loadtester:0.22.0\nghcr.io/fluxcd/flagger:1.21.0\nghcr.io/fluxcd/helm-controller:v0.23.1\nghcr.io/fluxcd/kustomize-controller:v0.27.1\nghcr.io/fluxcd/notification-controller:v0.25.2\n...\nThis section guides you to push installed artifacts to your private registry. Here's a Makefile to help you with each stage:
Expand to see Makefile contents .PHONY := all\n\n #set these variable with your custom configuration\nPRIVATE_HELM_REPO_NAME=private\n REGISTRY=localhost:5001\n WGE_VERSION=0.10.2\n\n WGE=mccp-$(WGE_VERSION)\nWGE_CHART=$(WGE).tgz\n\n all: images charts\n\n charts: pull-charts push-charts\n\n images:\n kubectl get pods --all-namespaces -o jsonpath=\"{.items[*].spec['containers','initContainers'][*].image}\" \\\n|tr -s '[[:space:]]' '\\n' | sort | uniq | grep -vE 'kindest|kube-(.*)|etcd|coredns' | xargs -L 1 -I {} ./image-sync.sh {} $(REGISTRY)\nkubectl get microvmmachinetemplates --all-namespaces -o jsonpath=\"{.items[*].spec.template.spec.kernel.image}\"|tr -s '[[:space:]]' '\\n' \\\n| sort | uniq | xargs -L 1 -I {} ./image-sync.sh {} $(REGISTRY)\n\npull-charts:\n curl -L https://s3.us-east-1.amazonaws.com/weaveworks-wkp/releases/charts-v3/$(WGE_CHART) --output $(WGE_CHART)\n\npush-charts:\n helm cm-push -f $(WGE_CHART) $(PRIVATE_HELM_REPO_NAME)\nThe image-sync.sh referenced in the images target of the the above Makefile is similar to:
skopeo copy docker://$1 docker://$2/$1 --preserve-digests --multi-arch=all\nSkopeo allows you to configure a range a security features to meet your requirements. For example, configuring trust policies before pulling or signing containers before making them available in your private network. Feel free to adapt the previous script to meet your security needs.
\u279c resources git:(docs-airgap-install) \u2717 make\nkubectl get microvmmachinetemplates --all-namespaces -o jsonpath=\"{.items[*].spec.template.spec.kernel.image}\"|tr -s '[[:space:]]' '\\n' \\\n| sort | uniq | xargs -L 1 -I {} ./image-pull-push.sh {} docker-registry:5000\n\n5.10.77: Pulling from weaveworks-liquidmetal/flintlock-kernel\nDigest: sha256:5ef5f3f5b42a75fdb69cdd8d65f5929430f086621e61f00694f53fe351b5d466\nStatus: Image is up to date for ghcr.io/weaveworks-liquidmetal/flintlock-kernel:5.10.77\nghcr.io/weaveworks-liquidmetal/flintlock-kernel:5.10.77\n...5.10.77: digest: sha256:5ef5f3f5b42a75fdb69cdd8d65f5929430f086621e61f00694f53fe351b5d466 size: 739\nAt this stage you have in your private registry both the Helm charts and container images required to install Weave GitOps Enterprise. Now you are ready to install WGE from your private registry.
Follow the instructions to install WGE with the following considerations:
An example of how it would look for Weave GitOps Enterprise is shown below.
Expand to view example WGE manifest weave-gitops-enterprise.yaml---\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: HelmRepository\nmetadata:\nname: weave-gitops-enterprise-charts\nnamespace: flux-system\nspec:\ninterval: 1m\nurl: http://helm-repo-chartmuseum:8080\n---\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: weave-gitops-enterprise\nnamespace: flux-system\nspec:\nchart:\nspec:\nchart: mccp\nversion: \"0.10.2\"\nsourceRef:\nkind: HelmRepository\nname: weave-gitops-enterprise-charts\nnamespace: flux-system\ninterval: 1m0s\ninstall:\ncrds: CreateReplace\nremediation:\nretries: 3\nupgrade:\ncrds: CreateReplace\nvalues:\nglobal:\ncapiEnabled: true\nenablePipelines: true\nenableTerraformUI: true\nclusterBootstrapController:\nenabled: true\n#images changed\ncluster-controller:\ncontrollerManager:\nkubeRbacProxy:\nimage:\nrepository: localhost:5001/gcr.io/kubebuilder/kube-rbac-proxy\ntag: v0.8.0\nmanager:\nimage:\nrepository: localhost:5001/docker.io/weaveworks/cluster-controller\ntag: v1.4.1\npolicy-agent:\nenabled: true\nimage: localhost:5001/weaveworks/policy-agent\npipeline-controller:\ncontroller:\nmanager:\nimage:\nrepository: localhost:5001/ghcr.io/weaveworks/pipeline-controller\nimages:\nclustersService: localhost:5001/docker.io/weaveworks/weave-gitops-enterprise-clusters-service:v0.10.2\nuiServer: localhost:5001/docker.io/weaveworks/weave-gitops-enterprise-ui-server:v0.10.2\nclusterBootstrapController: localhost:5001/weaveworks/cluster-bootstrap-controller:v0.4.0\nIndicate in the Cluster API configuration file clusterctl.yaml that you want to use images from the private repo by leveraging image overrides.
images:\nall:\nrepository: localhost:5001/registry.k8s.io/cluster-api\ninfrastructure-microvm:\nrepository: localhost:5001/ghcr.io/weaveworks-liquidmetal\nmake clusterctl-init to init capi using your private registry."},{"location":"enterprise/install-enterprise-azure/","title":"Azure and Weave GitOps Enterprise Installation ENTERPRISE","text":"Once you successfully create your Kubernetes cluster in Azure Marketplace, follow these steps to Install Weave GitOps Enterprise. These instructions apply to both Azure AKS and Azure ARC clusters\u2014they'll behave in the same way.
Tip
If you have already installed Flux, then Azure Flux will refuse to install.
"},{"location":"enterprise/install-enterprise-azure/#1-choose-the-gitops-option-in-the-marketplace","title":"1. Choose the \u201cGitOps\u201d Option in the Marketplace","text":"Search for Weave GitOps Enterprise in the \"Extensions + Applications\" of the Azure Marketplace. Click the \"GitOps\" option. This will take you to a screen that presents a first-class item called Type: Flux v2.
Click GitOps => Create.
Add the config name, namespace (default), scope: cluster, type (Flux v2), and continuous reconciliation option. Your entries should look like this:
All of the displayed properties for the Flux objects screen are the same as what you'd supply to Flux bootstrap.
"},{"location":"enterprise/install-enterprise-azure/#optional-install-capz-the-capi-provider","title":"Optional: Install CAPZ, the CAPI Provider","text":"If you are planning to manage or connect CAPI clusters to the WE service make sure you first install the CAPI provider. Then during the WE installation process be sure to select the \"Enable CAPI support\" checkbox.
"},{"location":"enterprise/install-enterprise-azure/#2-apply-the-entitlements-secret","title":"2. Apply the Entitlements Secret","text":"Contact sales@weave.works for a valid entitlements secret. This will come in the form of a file \u201centitlements.yaml\u201d. Apply it to the cluster:
kubectl apply -f entitlements.yaml\n(This section is the same as what you'll find in the main WGE install documentation.)
Here we provide guidance for GitHub, GitLab, BitBucket Server, and Azure DevOps.
GitHub requires no additional configuration for OAuth Git access
Create a GitLab OAuth application that will request api permissions to create pull requests on your behalf.
Follow the GitLab docs.
The application should have at least these scopes:
Add callback URLs to the application for each address the UI will be exposed on, e.g.:
Save your application, taking note of the Client ID and Client Secret. Save them into the git-provider-credentials secret, along with:
Replace values in this snippet and run:
kubectl create secret generic git-provider-credentials --namespace=flux-system \\\n--from-literal=\"GITLAB_CLIENT_ID=13457\" \\\n--from-literal=\"GITLAB_CLIENT_SECRET=24680\" \\\n--from-literal=\"GITLAB_HOSTNAME=git.example.com\" \\\n--from-literal=\"GIT_HOST_TYPES=git.example.com=gitlab\"\n
Create a new incoming application link from the BitBucket administration dashboard. You will be asked to enter a unique name and the redirect URL for the external application. The redirect URL should be set to <WGE dashboard URL>/oauth/bitbucketserver. You will also need to select permissions for the application. The minimum set of permissions needed for WGE to create pull requests on behalf of users is Repositories - Write. An example of configuring these settings is shown below.
Configuring a new incoming application link
Save your application and take note of the Client ID and Client Secret. Save them into the git-provider-credentials secret, along with:
Replace values in this snippet and run:
kubectl create secret generic git-provider-credentials --namespace=flux-system \\\n--from-literal=\"BITBUCKET_SERVER_CLIENT_ID=13457\" \\\n--from-literal=\"BITBUCKET_SERVER_CLIENT_SECRET=24680\" \\\n--from-literal=\"BITBUCKET_SERVER_HOSTNAME=git.example.com\" \\\n--from-literal=\"GIT_HOST_TYPES=git.example.com=bitbucket-server\"\nIf the secret is already present, use the following command to update it using your default editor:
kubectl edit secret generic git-provider-credentials --namespace=flux-system\nInfo
If BitBucket Server is running on the default port (7990), make sure you include the port number in the values of the secret. For example: GIT_HOST_TYPES=git.example.com:7990=bitbucket-server
Navigate to VisualStudio and register a new application, as explained in the docs. Set the authorization callback URL and select which scopes to grant. Set the callback URL to <WGE dashboard URL>/oauth/azuredevops.
Select the Code (read and write) scope from the list. This is necessary so that WGE can create pull requests on behalf of users. An example of configuring these settings is shown below.
Creating a new application
After creating your application, you will be presented with the application settings. Take note of the App ID and Client Secret values\u2014you will use them to configure WGE.
Application settings
In your cluster, create a secret named git-provider-credentials that contains the App ID and Client Secret values from the newly created application.
Replace values in this snippet and run:
kubectl create secret generic git-provider-credentials --namespace=flux-system \\\n--from-literal=\"AZURE_DEVOPS_CLIENT_ID=<App ID value>\" \\\n--from-literal=\"AZURE_DEVOPS_CLIENT_SECRET=<Client Secret value>\"\nWGE is now configured to ask users for authorization the next time a pull request must be created as part of using a template. Note that each user can view and manage which applications they have authorized by navigating to https://app.vsaex.visualstudio.com/me.
"},{"location":"enterprise/install-enterprise-azure/#4-configure-your-password","title":"4. Configure Your Password","text":"
First, install the Weave GitOps Enterprise CLI tool. To do this, you can use either brew or curl.
brew install weaveworks/tap/gitops-ee\ncurl --silent --location \"https://artifacts.wge.dev.weave.works/releases/bin/0.27.0/gitops-$(uname)-$(uname -m).tar.gz\" | tar xz -C /tmp\nsudo mv /tmp/gitops /usr/local/bin\ngitops version\n
Now, to login to the WGE UI, generate a bcrypt hash for your chosen password and store it as a secret in the Kubernetes cluster. There are several different ways to generate a bcrypt hash. Here, we'll use gitops get bcrypt-hash from our GitOps CLI.
PASSWORD=\"<Make up and insert a brand-new password here>\"\necho -n $PASSWORD | gitops get bcrypt-hash | kubectl create secret generic cluster-user-auth -n flux-system --from-literal=username=wego-admin --from-file=password=/dev/stdin\nA validation to know it\u2019s working:
kubectl get secret -n flux-system cluster-user-auth\nFirst, you'll get taken to the Weaveworks portal on the Azure platform, which provides your subscription details.
Search for Weave GitOps. Pick \"View private products\" and choose WGE. Fill out the forms, selecting your cluster, then choose \"Review and Create\".
"},{"location":"enterprise/install-enterprise-azure/#6-apply-extra-configuration","title":"6. Apply Extra Configuration","text":"Additional configuration is done through an optional ConfigMap:
apiVersion: v1\nkind: ConfigMap\nmetadata:\n name: cluster-service-extra-config\n namespace: flux-system\ndata:\n # disable TLS\nNO_TLS: \"true\"\nApply the configuration with:
kubectl apply -f cluster-service-extra-config.yaml\n\n# restart the clusters-service for changes to take effect\nkubectl -n flux-system rollout restart deploy/weave-gitops-enterprise-mccp-cluster-service\nNO_TLS \"false\" disable TLS CLUSTER_NAME \"management\" name of the management cluster AUTH_METHODS \"token-passthrough,user-account\" Which auth methods to use, valid values are 'oidc', 'token-pass-through' and 'user-account' OIDC_ISSUER_URL \"token-passthrough,user-account\" The URL of the OpenID Connect issuer OIDC_CLIENT_ID \"token-passthrough,user-account\" The client ID for the OpenID Connect client OIDC_CLIENT_SECRET \"token-passthrough,user-account\" The client secret to use with OpenID Connect issuer OIDC_REDIRECT_URL \"token-passthrough,user-account\" The OAuth2 redirect URL OIDC_TOKEN_DURATION \"1h\" The duration of the ID token. It should be set in the format: number + time unit (s,m,h) e.g., 20m OIDC_CLAIM_USERNAME \"email\" JWT claim to use as the user name. By default email, which is expected to be a unique identifier of the end user. Admins can choose other claims, such as sub or name, depending on their provider OIDC_CLAIM_GROUPS \"groups\" JWT claim to use as the user's group. If the claim is present it must be an array of strings CUSTOM_OIDC_SCOPES \"groups, openid, email, profile\" Customise the requested scopes for then OIDC authentication flow - openid will always be requested"},{"location":"enterprise/install-enterprise-azure/#7-check-that-it-works","title":"7. Check That It Works","text":"Go to the \"services and ingresses\" tab in the Azure portal and look for signs that the UI installed.
"},{"location":"enterprise/install-enterprise-azure/#troubleshooting","title":"Troubleshooting","text":"WGE will try and automatically install Flux on a new cluster. If this fails for some reason, or if you need a custom Flux installation, you can manually install it before installing WGE.
Click \"Next\" and add:
And under the \"Authentication\" section:
Click \"Next\". You'll see an option to create a Kustomisation, which is optional. To create one:
Click \"Save\". Then clicking \"Next\", which will give you a summary so you can review your input. Then click \"Create\". It will take about five minutes to deploy.
You'll get to a new screen, which at the top-right shows \"Notifications\" and will display creation of the Flux configuration. When your deployment succeeds, go to the resource and pin to your dashboard. Then go to your terminal to see if it works in kubectl. In the terminal you'll get the GitRepository and Kustomizations. You should then get a green \"succeeded\" checkmark.
The Kustomisations screen does not provide an option to inspect the path/target namespace\u2014you have to supply the target Namespace in the Kustomization object.
"},{"location":"enterprise/install-enterprise-azure/#next-steps","title":"Next Steps","text":"From this point, you can follow our generalized WGE installation instructions to configure TLS and log into the UI. Installing the Azure Marketplace product installs the Helm chart.
"},{"location":"enterprise/install-enterprise-cli/","title":"Install Weave GitOps Enterprise via CLI","text":"Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
You could install Weave GitOps Enterprise via gitops-ee bootstrap CLI command which is suitable for two main scenarios:
Each scenario is supported by an operation modes:
For those seeking other scenarios or fine-grain customisation Weave GitOps Enterprise manual install would be the recommended.
"},{"location":"enterprise/install-enterprise-cli/#getting-started","title":"Getting Started","text":""},{"location":"enterprise/install-enterprise-cli/#prerequisites","title":"Prerequisites","text":"Before you start make sure the following requirements are met:
gitops-ee CLI (> v0.35)","text":"Weave GitOps Enterprise Bootstrap functionality is available on Weave GitOps Enterprise CLI starting from version v0.35. If you haven't already, please install the latest gitops-ee CLI using this command.
brew install weaveworks/tap/gitops-ee\nPlease use the following command to start the installation wizard of Weave GitOps Enterprise.
InteractiveNon-Interactivegitops bootstrap\nYou could run the bootstrap command in non-interactive mode by providing the required configurations as flags. The following gives you an example to get started that you could adapt to your own context
gitops bootstrap \\\n--kubeconfig=$HOME/.kube/config \\\n--private-key=$HOME/.ssh/id_rsa --private-key-password=\"\" \\\n--version=\"0.35.0\" \\\n--domain-type=\"localhost\" \\\n--password=\"admin123\"\nFor more information about the CLI configurations, check the below sections here
"},{"location":"enterprise/install-enterprise-cli/#appendix","title":"Appendix","text":""},{"location":"enterprise/install-enterprise-cli/#understanding-gitops-ee-bootstrap","title":"Understandinggitops-ee bootstrap","text":"gitops-ee bootstrap is a workflow that will take you through the following stages:
Weave GitOps Enterprise runs on top of flux, the bootstrap CLI will check if flux is installed on the management cluster, and it will verify that it has the right version with valid git repository setup, and it is able to reconcile flux components properly. If flux is installed, but doesn't have a valid installation, the bootstrap CLI will terminate pending the fix or uninstall of current flux installation.
"},{"location":"enterprise/install-enterprise-cli/#verify-entitlement","title":"Verify Entitlement","text":"Weave GitOps Enterprise Entitlement is your obtained license to use our product. The Entitlements file is a Kubernetes secret that contains your licence. Bootstrapping checks that the secret exists on the management cluster, and that it is valid will check if it has valid content and the entitlement is not expired. To get the entitlement secret please contact sales@weave.works, then apply it on your management cluster with the name weave-gitops-enterprise-credentials under flux-system namespace.
In order for gitops-ee bootstrap to push WGE resources to the management cluster's git repository, you will be prompted to provide the private key used to access your repo via ssh. If the private key is encrypted, you will also be asked to provide the private key password.
Info
Disclaimer: The bootstrap CLI will ONLY use the private key to push WGE resources to your repo, and won't use it in any other way that can comprimise your repo or clusters security.
"},{"location":"enterprise/install-enterprise-cli/#select-wge-version","title":"Select WGE version","text":"The bootstrap CLI will prompt you to choose from the latest 3 versions of Weave GitOps Enterprise.
"},{"location":"enterprise/install-enterprise-cli/#create-cluster-user","title":"Create Cluster User","text":"You will be prompt to provide admin username and password, which will be used to access the dashboard. This will create admin secret with the credentials. If you already have previous admin credentials on your cluster, the installation will prompt you if you want to continue with the old credentials or exit and revoke them and re-run the installation.
"},{"location":"enterprise/install-enterprise-cli/#configure-dashboard-access","title":"Configure Dashboard Access","text":"To access Weave GitOps Enterprise dashboard, you have the two following options available:
After installation is successful. The CLI will print out the URL where you can access the dashboard.
"},{"location":"enterprise/install-enterprise-cli/#optional-configure-oidc","title":"(Optional) Configure OIDC","text":"OIDC configuration will enable you to login with OIDC provider beside, or instead of the admin credentials. Afte the installation is complete, you will be prompt if you want to configure OIDC access. If you don't want to set it up right away, you can do it later by running gitops-ee bootstrap auth --type=oidc command.
To configure OIDC access, you will be asked to provide the following values: DiscoveryUrl this will verify that OIDC is accessible and get the issuerUrl from the OIDC settings. clientID & clientSecret that you have configured on your OIDC static-clients.
Note
Please don't forget to add a new static-client on your OIDC provider settings with the redirectURI your-domain/oauth2/callback for example http://localhost:3000/oauth2/callback
Info
To purchase an entitlement to Weave GitOps Enterprise, please contact sales@weave.works. There is no need to install the open source version of Weave GitOps before installing Weave GitOps Enterprise.
"},{"location":"enterprise/install-enterprise/#prerequisites","title":"Prerequisites","text":"To get up and running with Weave GitOps Enterprise: - create a Kubernetes cluster - add your cluster to kubeconfig\u2014which you'll get from Kubernetes\u2014so that the kubeconfig correctly points to the management cluster - create a Git repository; in the instructions below, we refer to a fleet-infra repository - configure your Git client properly (if using GitHub, for example, then review their docs on setting your username and your email address) - obtain a valid entitlement secret from Weaveworks and apply it to your cluster - install a compatible version of Flux onto your cluster; see below for how-to guidance
To do this, you can use either brew or curl.
HomebrewCurlbrew install weaveworks/tap/gitops-ee\nexport VERSION=<VERSION>\ncurl --silent --location \"https://artifacts.wge.dev.weave.works/releases/bin/${VERSION}/gitops-$(uname)-$(uname -m).tar.gz\" | tar xz -C /tmp\nsudo mv /tmp/gitops /usr/local/bin\ngitops version\nflux bootstrap Command","text":"The flux bootstrap command enables you to deploy Flux on a cluster the GitOps way. Go here for more information about the command.
flux bootstrap github \\\n--owner=<github username> \\\n--repository=fleet-infra \\\n--branch=main \\\n--path=./clusters/management \\\n--personal \\\n--components-extra image-reflector-controller,image-automation-controller\nflux bootstrap gitlab \\\n--owner=<gitlab username> \\\n--repository=fleet-infra \\\n--branch=main \\\n--path=./clusters/management \\\n--personal \\\n--components-extra image-reflector-controller,image-automation-controller\nYour private Git repo should have a clusters/management folder that includes the manifests Flux needs to operate, and that also generates a key value pair for Flux to access the repo.
At this point your Flux management cluster should be running. Take a look at the repository you created earlier.
"},{"location":"enterprise/install-enterprise/#apply-your-entitlements-secret-to-your-cluster","title":"Apply Your Entitlements Secret to Your Cluster","text":"As noted above, you receive your entitlements secret by contacting sales@weave.works. Use this command to apply it to the cluster:
kubectl apply -f entitlements.yaml\nThere are two supported methods for logging in to the dashboard, that work with standard Kubernetes RBAC: - Login via an OIDC provider: recommended, as this will allow you to control permissions for existing users and groups that have already been configured to use OIDC. OIDC decouples the need to manage user lists from the application, allowing it to be managed via a central system designed for that purpose (i.e. the OIDC provider). OIDC also enables the creation of groups\u2014either via your provider's own systems or by using a connector like Dex. - Login via a cluster user account: which is insecure, and which we only recommend for local and development environments or if you need to activate emergency access to a damaged cluster. However, it is an option if an OIDC provider is not available.
You may decide to give your engineering teams access to the WGE dashboard so they can view and manage their workloads. In this case, you will want to secure dashboard access and restrict who can interact with it. Weave GitOps Enterprise integrates with your OIDC provider and uses standard Kubernetes RBAC to give you fine-grained control of the dashboard users' permissions.
OIDC extends the OAuth2 authorization protocol by including an additional field (ID Token) that contains information (claims) about a user's identity. After a user successfully authenticates with the OIDC provider, Weave GitOps Enterprise uses this information to impersonate the user in any calls to the Kubernetes API. This allows cluster administrators to use RBAC rules to control access to the cluster and the dashboard.
Login via an OIDC providerConfiguring OIDC with Dex and GitHubLogin via a cluster user accountTo login via your OIDC provider, create a Kubernetes secret to store the OIDC configuration. This configuration consists of the following parameters:
Parameter Description DefaultissuerURL The URL of the issuer; typically, the discovery URL without a path clientID The client ID set up for Weave GitOps in the issuer clientSecret The client secret set up for Weave GitOps in the issuer redirectURL The redirect URL set up for Weave GitOps in the issuer\u2014typically the dashboard URL, followed by /oauth2/callback tokenDuration The time duration that the ID Token will remain valid after successful authentication \"1h0m0s\" tokenDuration The time duration that the ID Token will remain valid after successful authentication \"1h0m0s\" oidcUsernamePrefix The prefix added to users when impersonating API calls to the Kubernetes API, equivalent to --oidc-username-prefix oidcGroupsPrefix The prefix added to groups when impersonating API calls to the Kubernetes API, equivalent to --oidc-groups-prefix Ensure that your OIDC provider has been set up with a client ID/secret and the dashboard's redirect URL.
Create a secret named oidc-auth in the flux-system namespace with these parameters set:
kubectl create secret generic oidc-auth \\\n--namespace flux-system \\\n--from-literal=issuerURL=<oidc-issuer-url> \\\n--from-literal=clientID=<client-id> \\\n--from-literal=clientSecret=<client-secret> \\\n--from-literal=redirectURL=<redirect-url> \\\n--from-literal=tokenDuration=<token-duration>\nOnce the HTTP server starts, unauthenticated users will have to click 'Login With OIDC Provider' to log in or use the cluster account (if configured). Upon successful authentication, the users' identities will be impersonated in any calls made to the Kubernetes API, as part of any action they take in the dashboard. By default the Helm chart will configure RBAC correctly, but we recommend reading the service account and user permissions pages to understand which actions are needed for Weave GitOps to function correctly.
Important
This is an insecure method of securing your dashboard which we only recommend for local and development environments, or if you need to activate emergency access to a damaged cluster.
Note also that this mechanism only exists for a single user. You will not be able to create multiple users. Weave GitOps does not provide its own authentication mechanism. For secure and fully-featured authentication we strongly recommend using an OIDC provider, as described in the other tab.
"},{"location":"enterprise/install-enterprise/#customization","title":"Customization","text":"For some OIDC configurations, you may need to customise the requested scopes or claims.
The oidcUsernamePrefix and oidcGroupsPrefix work in the same way as the Kubernetes kube-apiserver command-line options, if you need them for Kubernetes, you will likely need them here.
By default, the following scopes are requested: \"openid\",\"offline_access\",\"email\",\"groups\".
The \"openid\" scope is mandatory for OpenID auth and will be added if not provided. The \"email\" and \"groups\" scopes are commonly used as unique identifiers in organisations.
\"offline_access\" allows us to refresh OIDC tokens to keep login sessions alive for as long as a refresh token is valid. You can, however, change the defaults.
kubectl create secret generic oidc-auth \\\n--namespace flux-system \\\n--from-literal=issuerURL=<oidc-issuer-url> \\\n--from-literal=clientID=<client-id> \\\n--from-literal=clientSecret=<client-secret> \\\n--from-literal=redirectURL=<redirect-url> \\\n--from-literal=tokenDuration=<token-duration> \\\n--from-literal=customScopes=custom,scopes\ncustomScopes key is a comma-separated list of scopes to request. In this case, \"custom\", \"scopes\", and \"openid\" would be requested."},{"location":"enterprise/install-enterprise/#claims","title":"Claims","text":"By default, the following claims are parsed from the OpenID ID Token \"email\" and \"groups\". These are presented as the user and groups when WGE communicates with your Kubernetes API server.
This is equivalent to configuring your kube-apiserver with --oidc-username-claim=email --oidc-groups-claim=groups.
Again, you can configure these from the oidc-auth Secret.
kubectl create secret generic oidc-auth \\\n--namespace flux-system \\\n--from-literal=issuerURL=<oidc-issuer-url> \\\n--from-literal=clientID=<client-id> \\\n--from-literal=clientSecret=<client-secret> \\\n--from-literal=redirectURL=<redirect-url> \\\n--from-literal=tokenDuration=<token-duration> \\\n--from-literal=claimUsername=sub \\\n--from-literal=claimGroups=groups\nkube-apiserver configuration."},{"location":"enterprise/install-enterprise/#configuring-oidc-with-dex-and-github","title":"Configuring OIDC with Dex and GitHub","text":"This example uses Dex and its GitHub connector to show you how to log in to the Weave GitOps dashboard by authenticating with your GitHub account. It assumes you have already installed Weave GitOps on a Kubernetes cluster, per the instructions above, and have also enabled TLS.
Dex is an identity service that uses OpenID Connect to drive authentication for other apps. There are other solutions for identity and access management, such as Keycloak.
Create a namespace where you will install Dex:
---\napiVersion: v1\nkind: Namespace\nmetadata:\nname: dex\nGet a GitHub ClientID and Client secret by creating a new OAuth application.
kubectl create secret generic github-client \\\n--namespace=dex \\\n--from-literal=client-id=${GITHUB_CLIENT_ID} \\\n--from-literal=client-secret=${GITHUB_CLIENT_SECRET}\nUse HelmRepository and HelmRelease objects to let Flux deploy everything.
---\napiVersion: source.toolkit.fluxcd.io/v1beta1\nkind: HelmRepository\nmetadata:\nname: dex\nnamespace: dex\nspec:\ninterval: 1m\nurl: https://charts.dexidp.io\n---\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: dex\nnamespace: dex\nspec:\ninterval: 5m\nchart:\nspec:\nchart: dex\nversion: 0.15.3\nsourceRef:\nkind: HelmRepository\nname: dex\nnamespace: dex\ninterval: 1m\nvalues:\nenvVars:\n- name: GITHUB_CLIENT_ID\nvalueFrom:\nsecretKeyRef:\nname: github-client\nkey: client-id\n- name: GITHUB_CLIENT_SECRET\nvalueFrom:\nsecretKeyRef:\nname: github-client\nkey: client-secret\nconfig:\n# Set it to a valid URL\nissuer: https://dex.dev.example.tld\n\n# See https://dexidp.io/docs/storage/ for more options\nstorage:\ntype: memory\n\nstaticClients:\n- name: 'Weave GitOps'\nid: weave-gitops\nsecret: AiAImuXKhoI5ApvKWF988txjZ+6rG3S7o6X5En\nredirectURIs:\n- 'https://localhost:9001/oauth2/callback'\n- 'https://0.0.0.0:9001/oauth2/callback'\n- 'http://0.0.0.0:9001/oauth2/callback'\n- 'http://localhost:4567/oauth2/callback'\n- 'https://localhost:4567/oauth2/callback'\n- 'http://localhost:3000/oauth2/callback'\n\nconnectors:\n- type: github\nid: github\nname: GitHub\nconfig:\nclientID: $GITHUB_CLIENT_ID\nclientSecret: $GITHUB_CLIENT_SECRET\nredirectURI: https://dex.dev.example.tld/callback\norgs:\n- name: weaveworks\nteams:\n- team-a\n- team-b\n- QA\n- name: ww-test-org\ningress:\nenabled: true\nclassName: nginx\nannotations:\ncert-manager.io/cluster-issuer: letsencrypt-prod\nhosts:\n- host: dex.dev.example.tld\npaths:\n- path: /\npathType: ImplementationSpecific\ntls:\n- hosts:\n- dex.dev.example.tld\nsecretName: dex-dev-example-tld\nAn important part of the configuration is the orgs field on the GitHub connector, which allows you to define groups within a GitHub organisation:
orgs:\n- name: weaveworks\nteams:\n- team-a\n- team-b\n- QA\nIn this example, the GitHub organisation is weaveworks and all members of the team-a, team-b, and QA teams can authenticate. Group membership is added to the user.
Based on these groups, we can bind roles to groups:
Expand to see group role bindings---\napiVersion: rbac.authorization.k8s.io/v1\nkind: RoleBinding\nmetadata:\nname: wego-test-user-read-resources\nnamespace: flux-system\nsubjects:\n- kind: Group\nname: weaveworks:QA\nnamespace: flux-system\nroleRef:\nkind: Role\nname: wego-admin-role\napiGroup: rbac.authorization.k8s.io\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: Role\nmetadata:\nname: wego-admin-role\nnamespace: flux-system\nrules:\n- apiGroups: [\"\"]\nresources: [\"secrets\", \"pods\" ]\nverbs: [ \"get\", \"list\" ]\n- apiGroups: [\"apps\"]\nresources: [ \"deployments\", \"replicasets\"]\nverbs: [ \"get\", \"list\" ]\n- apiGroups: [\"kustomize.toolkit.fluxcd.io\"]\nresources: [ \"kustomizations\" ]\nverbs: [ \"get\", \"list\", \"patch\" ]\n- apiGroups: [\"helm.toolkit.fluxcd.io\"]\nresources: [ \"helmreleases\" ]\nverbs: [ \"get\", \"list\", \"patch\" ]\n- apiGroups: [\"source.toolkit.fluxcd.io\"]\nresources: [\"buckets\", \"helmcharts\", \"gitrepositories\", \"helmrepositories\", \"ocirepositories\"]\nverbs: [\"get\", \"list\", \"patch\"]\n- apiGroups: [\"\"]\nresources: [\"events\"]\nverbs: [\"get\", \"watch\", \"list\"]\nIn the same way, we can bind cluster roles to a group:
Expand to see group cluster role bindings---\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRoleBinding\nmetadata:\nname: weaveworks:team-a\nsubjects:\n- kind: Group\nname: weaveworks:team-a\napiGroup: rbac.authorization.k8s.io\nroleRef:\nkind: ClusterRole\nname: cluster-admin\napiGroup: rbac.authorization.k8s.io\nFor a static user, add staticPasswords to the config:
spec:\nvalues:\nconfig:\nstaticPasswords:\n- email: \"admin@example.tld\"\nhash: \"$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W\"\nusername: \"admin\"\nuserID: \"08a8684b-db88-4b73-90a9-3cd1661f5466\"\nGenerate a static user password via the gitops CLI:
PASSWORD=\"<your password>\"\necho -n $PASSWORD | gitops get bcrypt-hash\n$2a$10$OS5NJmPNEb13UgTOSKnMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q\nUsing the \"Login with OIDC Provider\" button:
We have to authorize the GitHub OAuth application:
After that, grant access to Dex:
Now we are logged in with our GitHub user and can see all of the resources we have access to:
"},{"location":"enterprise/install-enterprise/#configuring-the-emergency-user","title":"Configuring the Emergency User","text":"Before you log in via the emergency user account, you need to generate a bcrypt hash for your chosen password and store it as a secret in Kubernetes. There are several different ways to generate a bcrypt hash. This guide uses gitops get bcrypt-hash from our CLI.
Generate the password by running:
PASSWORD=\"<your password>\"\necho -n $PASSWORD | gitops get bcrypt-hash\n$2a$10$OS5NJmPNEb13UgTOSKnMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q\nNow create a Kubernetes secret to store your chosen username and the password hash:
kubectl create secret generic cluster-user-auth \\\n--namespace flux-system \\\n--from-literal=username=wego-admin \\\n--from-literal=password='$2a$10$OS5NJmPNEb13UTOSKngMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q'\nYou should now be able to login via the cluster user account using your chosen username and password.
"},{"location":"enterprise/install-enterprise/#updating-the-emergency-user","title":"Updating the Emergency User","text":"To change either the username or the password, recreate the cluster-user-auth with the new details.
Only one emergency user can be created this way. To add more users, enable an OIDC provider.
"},{"location":"enterprise/install-enterprise/#user-permissions","title":"User Permissions","text":"By default, both a ClusterRole and Role are generated for the emergency user. Both have the same permissions, with the former being optional and the latter being bound to the flux-system namespace (where Flux stores its resources by default). The default set of rules are configured like this:
rules:\n# Flux Resources\n- apiGroups: [\"source.toolkit.fluxcd.io\"]\nresources: [ \"buckets\", \"helmcharts\", \"gitrepositories\", \"helmrepositories\", \"ocirepositories\" ]\nverbs: [ \"get\", \"list\", \"watch\", \"patch\" ]\n\n- apiGroups: [\"kustomize.toolkit.fluxcd.io\"]\nresources: [ \"kustomizations\" ]\nverbs: [ \"get\", \"list\", \"watch\", \"patch\" ]\n\n- apiGroups: [\"helm.toolkit.fluxcd.io\"]\nresources: [ \"helmreleases\" ]\nverbs: [ \"get\", \"list\", \"watch\", \"patch\" ]\n\n- apiGroups: [ \"notification.toolkit.fluxcd.io\" ]\nresources: [ \"providers\", \"alerts\" ]\nverbs: [ \"get\", \"list\", \"watch\", \"patch\" ]\n\n- apiGroups: [\"infra.contrib.fluxcd.io\"]\nresources: [\"terraforms\"]\nverbs: [ \"get\", \"list\", \"watch\", \"patch\" ]\n\n# Read access for all other Kubernetes objects\n- apiGroups: [\"*\"]\nresources: [\"*\"]\nverbs: [ \"get\", \"list\", \"watch\" ]\nThese permissions give the emergency user Administrator-level powers. We do not advise leaving it active on production systems.
If required, the permissions can be expanded with the rbac.additionalRules field in the Helm Chart. Follow the instructions in the next section in order to configure RBAC correctly.
To remove the emergency user as a login method, set the following values in the Helm Chart:
#\nadminUser:\ncreate: false\n#\nadditionalArgs:\n- --auth-methods=oidc\n#\nIf you are disabling an already existing emergency user, you will need to manually delete the Kubernetes Secret and any User Roles that were created on the cluster.
"},{"location":"enterprise/install-enterprise/#gitops-dashboard-service-account-permissions","title":"GitOps Dashboard Service Account Permissions","text":"This section covers the service account permissions for the Weave GitOps application, which the WGE UI requires to work. The default permissions will generate a cluster role that includes the permissions:
rules:\n- apiGroups: [\"\"]\nresources: [\"users\", \"groups\"] verbs: [ \"impersonate\" ]\n- apiGroups: [\"\"]\nresources: [ \"secrets\" ]\nverbs: [ \"get\", \"list\" ]\n- apiGroups: [ \"\" ]\nresources: [ \"namespaces\" ]\nverbs: [ \"get\", \"list\" ]\nThese allow the pod to do three things: - Impersonate the user and operate in the cluster as them - Read the available namespaces; this is required to understand users' permissions - Read the cluster-user-auth and oidc-auth secrets, the default secrets to store the emergency cluster user account and OIDC configuration (see securing access to the dashboard)
The primary way Weave GitOps queries the Kube API is via impersonation. The permissions granted to users and groups that Weave GitOps can impersonate will determine the scope of actions that WGE can take within your cluster.
The application, not the cluster, authenticates the user, either via the emergency cluster user credentials or OIDC. Then it makes Kube API calls on the user's behalf. This is equivalent to making a kubectl call like:
$ kubectl get deployments --as aisha@example.com\nAssuming the user aisha@example.com has permissions to get deployments within the cluster, this will return those deployments. The same occurs within the application, so properly configuring application permissions is very important. Without proper restrictions the application can impersonate very powerful users or groups. For example, the system:masters is a group generally bound to the cluster-admin role, which can do anything.
The application itself uses get namespace permissions to pre-cache the list of available namespaces. As the user accesses resources their permissions within various namespaces is also cached to speed up future operations.
"},{"location":"enterprise/install-enterprise/#reading-the-cluster-user-auth-and-oidc-auth-secrets","title":"Reading thecluster-user-auth and oidc-auth Secrets","text":"The cluster-user-auth and oidc-auth secrets provide information for authenticating to the application. The former holds the username and bcrypt-hashed password for the emergency user, and the latter holds OIDC configuration.
The application needs to be able to access these secrets in order to authenticate users.
"},{"location":"enterprise/install-enterprise/#user-permissions_1","title":"User Permissions","text":"This section discusses the Kubernetes permissions needed by Weave GitOps application users and groups. At a minimum, a User should be bound to a Role in the flux-system namespace\u2014which is where Flux stores its resources by default\u2014with the following permissions:
rules:\n# Flux Resources\n- apiGroups: [\"source.toolkit.fluxcd.io\"]\nresources: [ \"buckets\", \"helmcharts\", \"gitrepositories\", \"helmrepositories\", \"ocirepositories\" ]\nverbs: [ \"get\", \"list\", \"watch\", \"patch\" ]\n\n- apiGroups: [\"kustomize.toolkit.fluxcd.io\"]\nresources: [ \"kustomizations\" ]\nverbs: [ \"get\", \"list\", \"watch\", \"patch\" ]\n\n- apiGroups: [\"helm.toolkit.fluxcd.io\"]\nresources: [ \"helmreleases\" ]\nverbs: [ \"get\", \"list\", \"watch\", \"patch\" ]\n\n- apiGroups: [ \"notification.toolkit.fluxcd.io\" ]\nresources: [ \"providers\", \"alerts\" ]\nverbs: [ \"get\", \"list\", \"watch\", \"patch\" ]\n\n- apiGroups: [\"infra.contrib.fluxcd.io\"]\nresources: [\"terraforms\"]\nverbs: [ \"get\", \"list\", \"watch\", \"patch\" ]\n\n# Read access for all other Kubernetes objects\n- apiGroups: [\"*\"]\nresources: [\"*\"]\nverbs: [ \"get\", \"list\", \"watch\" ]\nFor a wider scope, the User can be bound to a ClusterRole with the same set.
On top of this you can add other permissions to view WGE resources like GitOpsSets and Templates.
The following table lists resources that Flux works with directly.
API Group Resources Permissions kustomize.toolkit.fluxcd.io kustomizations get, list, patch helm.toolkit.fluxcd.io Helm Releases get, list, patch source.toolkit.fluxcd.io buckets, Helm charts, Git repositories, Helm repositories, OCI repositories get, list, patch notification.toolkit.fluxcd.io providers, alerts get, list infra.contrib.fluxcd.io Terraform get, list, patchWeave GitOps needs to be able to query the CRDs that Flux uses before it can accurately display Flux state. The get and list permissions facilitate this.
The patch permissions are used for two features: to suspend and resume reconciliation of a resource by modifying the 'spec' of a resource, and to force reconciliation of a resource by modifying resource annotations. These features work in the same way that flux suspend, flux resume, and flux reconcile does on the CLI.
Weave GitOps reads basic resources so that it can monitor the effect that Flux has on what's running.
Reading secrets enables Weave GitOps to monitor the state of Helm releases as that's where it stores the state by default. For clarity this these are the Helm release objects not the Flux HelmRelease resource (which are dealt with by the earlier section).
Flux communicates the status of itself primarily via events. These events will show when reconciliations start and stop, whether they're successful, and information as to why they're not.
"},{"location":"enterprise/install-enterprise/#login-ui","title":"Login UI","text":"The label of the OIDC button on the login screen is configurable via a feature flag environment variable. This can give your users a more familiar experience when logging in.
Adjust the configuration in the Helm values.yaml file or the spec.values section of the Weave GitOps HelmRelease resource:
extraEnvVars:\n- name: WEAVE_GITOPS_FEATURE_OIDC_BUTTON_LABEL\nvalue: \"Login with ACME\"\nThis section is purposefully vague as we intend to give a broad idea of how to implement such a system. The specifics will dependent on your circumstances and goals.
Our general recommendation is to use OIDC and a small number of groups that Weave GitOps can impersonate.
Configuring Weave GitOps to impersonate Kubernetes groups rather than users has the following benefits: - A user's permissions for impersonation by Weave GitOps can be separate from any other permissions that they may or may not have within the cluster. - Users do not have to be individually managed within the cluster and can have their permissions managed together.
"},{"location":"enterprise/install-enterprise/#example-setup","title":"Example Setup","text":"Assume that your company has the following people in OIDC: - Aisha, a cluster admin, who should have full admin access to Weave GitOps - Brian, lead of Team-A, who should have admin permissions to their team's namespace in Weave GitOps and read-only otherwise - June and Jo, developers in Team-A who should have read-only access to Weave GitOps
You can then create three groups:
Using OIDC for cluster and Weave GitOps Authentication
If the same OIDC provider is used to authenticate a user with the cluster itself (e.g. for use with kubectl) and to Weave GitOps then, depending on OIDC configuration, they may end up with the super-set of their permissions from Weave GitOps and any other permissions granted to them.
This can lead to unintended consequences, like viewing secrets. To avoid this, OIDC providers will often let you configure which groups are returned to which clients. The Weave GitOps groups should not be returned to the cluster client (and vice versa).
The yaml to configure these permissions would look roughly like:
Expand to see example RBAC # Admin cluster role\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRole\nmetadata:\nname: wego-admin-cluster-role\nrules:\n- apiGroups: [\"\"]\nresources: [\"secrets\", \"pods\" ]\nverbs: [ \"get\", \"list\" ]\n- apiGroups: [\"apps\"]\nresources: [ \"deployments\", \"replicasets\"]\nverbs: [ \"get\", \"list\" ]\n- apiGroups: [\"kustomize.toolkit.fluxcd.io\"]\nresources: [ \"kustomizations\" ]\nverbs: [ \"get\", \"list\", \"patch\" ]\n- apiGroups: [\"helm.toolkit.fluxcd.io\"]\nresources: [ \"helmreleases\" ]\nverbs: [ \"get\", \"list\", \"patch\" ]\n- apiGroups: [\"source.toolkit.fluxcd.io\"]\nresources: [ \"buckets\", \"helmcharts\", \"gitrepositories\", \"helmrepositories\", \"ocirepositories\" ]\nverbs: [ \"get\", \"list\", \"patch\" ]\n- apiGroups: [\"\"]\nresources: [\"events\"]\nverbs: [\"get\", \"watch\", \"list\"]\n---\n# Read-only cluster role\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRole\nmetadata:\nname: wego-readonly-role\nrules:\n# All the 'patch' permissions have been removed\n- apiGroups: [\"\"]\nresources: [\"secrets\", \"pods\" ]\nverbs: [ \"get\", \"list\" ]\n- apiGroups: [\"apps\"]\nresources: [ \"deployments\", \"replicasets\"]\nverbs: [ \"get\", \"list\" ]\n- apiGroups: [\"kustomize.toolkit.fluxcd.io\"]\nresources: [ \"kustomizations\" ]\nverbs: [ \"get\", \"list\" ]\n- apiGroups: [\"helm.toolkit.fluxcd.io\"]\nresources: [ \"helmreleases\" ]\nverbs: [ \"get\", \"list\" ]\n- apiGroups: [\"source.toolkit.fluxcd.io\"]\nresources: [ \"buckets\", \"helmcharts\", \"gitrepositories\", \"helmrepositories\", \"ocirepositories\" ]\nverbs: [ \"get\", \"list\" ]\n- apiGroups: [\"\"]\nresources: [\"events\"]\nverbs: [\"get\", \"watch\", \"list\"]\n---\n# Bind the cluster admin role to the wego-admin group\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRoleBinding\nmetadata:\nname: wego-cluster-admin\nsubjects:\n- kind: Group\nname: wego-admin # only Aisha is a member\napiGroup: rbac.authorization.k8s.io\nroleRef:\nkind: ClusterRole\nname: wego-admin-cluster-role\napiGroup: rbac.authorization.k8s.io\n---\n# Bind the admin role in the team-a namespace for the wego-team-a-admin group\napiVersion: rbac.authorization.k8s.io/v1\nkind: RoleBinding\nmetadata:\nname: wego-team-a-admin-role\nnamespace: team-a\nsubjects:\n- kind: Group\nname: wego-team-a-admin # Aisha & Brian are members\napiGroup: rbac.authorization.k8s.io\nroleRef:\n# Use the cluster role to set rules, just bind them in the team-a namespace\nkind: ClusterRole\nname: wego-admin-role\napiGroup: rbac.authorization.k8s.io\n---\n# Bind the read-only role to the read-only group\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRoleBinding\nmetadata:\nname: wego-readonly-role\nsubjects:\n- kind: Group\nname: wego-readonly # Everyone is a member\napiGroup: rbac.authorization.k8s.io\nroleRef:\nkind: ClusterRole\nname: wego-readonly-role\napiGroup: rbac.authorization.k8s.io\n---\nHere we provide guidance for GitHub, GitLab, BitBucket Server, and Azure DevOps.
GitHubBitBucket ServerAzure DevOpsGitHub requires no additional configuration for OAuth git access
Create a GitLab OAuth application that will request api permissions to create pull requests on your behalf.
Follow the GitLab docs.
The application should have at least these scopes:
Add callback URLs to the application for each address the UI will be exposed on, e.g.:
Save your application, taking note of the Client ID and Client Secret. Save them into the git-provider-credentials secret, along with:
Replace values in this snippet and run:
kubectl create secret generic git-provider-credentials --namespace=flux-system \\\n--from-literal=\"GITLAB_CLIENT_ID=13457\" \\\n--from-literal=\"GITLAB_CLIENT_SECRET=24680\" \\\n--from-literal=\"GITLAB_HOSTNAME=git.example.com\" \\\n--from-literal=\"GIT_HOST_TYPES=git.example.com=gitlab\"\nCreate a new incoming application link from the BitBucket administration dashboard. You will be asked to enter a unique name and the redirect URL for the external application. The redirect URL should be set to <WGE dashboard URL>/oauth/bitbucketserver. You will also need to select permissions for the application. The minimum set of permissions needed for WGE to create pull requests on behalf of users is Repositories - Write. An example of configuring these settings is shown below.
Configuring a new incoming application link
Save your application and take note of the Client ID and Client Secret. Save them into the git-provider-credentials secret, along with:
Replace values in this snippet and run:
kubectl create secret generic git-provider-credentials --namespace=flux-system \\\n--from-literal=\"BITBUCKET_SERVER_CLIENT_ID=13457\" \\\n--from-literal=\"BITBUCKET_SERVER_CLIENT_SECRET=24680\" \\\n--from-literal=\"BITBUCKET_SERVER_HOSTNAME=git.example.com\" \\\n--from-literal=\"GIT_HOST_TYPES=git.example.com=bitbucket-server\"\nIf the secret is already present, use the following command to update it using your default editor:
kubectl edit secret generic git-provider-credentials --namespace=flux-system\nInfo
If BitBucket Server is running on the default port (7990), make sure you include the port number in the values of the secret. For example: GIT_HOST_TYPES=git.example.com:7990=bitbucket-server
Navigate to VisualStudio and register a new application, as explained in the docs. Set the authorization callback URL and select which scopes to grant. Set the callback URL to <WGE dashboard URL>/oauth/azuredevops.
Select the Code (read and write) scope from the list. This is necessary so that WGE can create pull requests on behalf of users. An example of configuring these settings is shown below.
Creating a new application
After creating your application, you will be presented with the application settings. Take note of the App ID and Client Secret values\u2014you will use them to configure WGE.
Application settings
In your cluster, create a secret named git-provider-credentials that contains the App ID and Client Secret values from the newly created application.
Replace values in this snippet and run:
kubectl create secret generic git-provider-credentials --namespace=flux-system \\\n--from-literal=\"AZURE_DEVOPS_CLIENT_ID=<App ID value>\" \\\n--from-literal=\"AZURE_DEVOPS_CLIENT_SECRET=<Client Secret value>\"\nWGE is now configured to ask users for authorization the next time a pull request must be created as part of using a template. Note that each user can view and manage which applications they have authorized by navigating to https://app.vsaex.visualstudio.com/me.
"},{"location":"enterprise/install-enterprise/#tls-configuration","title":"TLS Configuration","text":"By default, the WGE UI pod will listen on port 8000 with TLS enabled. WGE will generate and use a self-signed certificate for this purpose.
It can then be accessed via port-forwarding:
kubectl port-forward --namespace flux-system svc/clusters-service 8000:8000
If you're using an ingress controller to terminate TLS you can disable it in the Helm release:
values:\ntls:\nenabled: false\nOther ingress conguration changes can be made via the ingress configuration
values:\ningress:\nenabled: true\n... other parameters specific to the ingress type ...\nWe deploy WGE via a Helm chart. We'll save and adapt the below template before committing it in Git to a Flux-reconciled path.
Clone the newly created repo locally. We're gonna add some things!
git clone git@<provider>:<username>/fleet-infra\ncd fleet-infra\nDownload the helm-release to clusters/management/weave-gitops-enterprise.yaml.
import ExampleWGE from \"../assets/example-enterprise-helm.yaml\"; import ExampleWGEContent from \"!!raw-loader!../assets/example-enterprise-helm.yaml\";
Expand to see file contentsOnce you have copied the above file, open and adjust the following configuration options:
"},{"location":"enterprise/install-enterprise/#valuesconfigcapirepositoryurl","title":"values.config.capi.repositoryURL","text":"Ensure this has been set to your repository URL.
"},{"location":"enterprise/install-enterprise/#valuesconfigcapirepositorypath","title":"values.config.capi.repositoryPath","text":"By default, WGE will create new clusters in the clusters/management/clusters path. You can configure it with values.config.capi.repositoryPath. You might what to change it to clusters/my-cluster/cluster if you configured Flux to reconcile ./clusters/my-cluster instead.
values.config.capi.repositoryClustersPath","text":"The other important path to configure is where you'll store applications and workloads run on the new cluster. By default this is ./clusters. When a new cluster is specified, any selected profiles will be written to ./clusters/{.namespace}/{.clusterName}/profiles.yaml. When the new cluster is bootstrapped, Flux will sync the ./clusters/{.namespace}/{.clusterName} path.
To login to the WGE UI, generate a bcrypt hash for your chosen password and store it as a secret in the Kubernetes cluster. There are several different ways to generate a bcrypt hash. Here, we'll use gitops get bcrypt-hash from our CLI.
PASSWORD=\"<Make up and insert a brand-new password here>\"\necho -n $PASSWORD | gitops get bcrypt-hash | kubectl create secret generic cluster-user-auth -n flux-system --from-literal=username=wego-admin --from-file=password=/dev/stdin\nA validation to know it\u2019s working:
kubectl get secret -n flux-system cluster-user-auth\nPolicy agent comes packaged with the WGE chart. To install it, set the following values:
Commit and push all the files
git add clusters/management/weave-gitops-enterprise.yaml\ngit commit -m \"Deploy Weave GitOps Enterprise\"\ngit push\nFlux will reconcile the helm-release and WGE will be deployed into the cluster. You can check the flux-system namespace to verify all pods are running.
Here are a couple of options for you to take your next steps with WGE. Explore one option or all of them, in no particular order.
See also our guide to installing Weave GitOps Enterprise on Azure: - An Azure cluster deployed with either the Azure Portal or Azure CLI tools. - Azure Flux add-on deployed by adding a GitOps configuration, either via the Azure Portal or the CLI tool.
Note that this documentation applies to both Azure AKS and Azure ARC clusters.
"},{"location":"enterprise/join-cluster-azure-flux/#initial-status","title":"Initial Status","text":"The Azure cluster already has the Azure Flux add-on installed. This differs from CNCF Flux in that there are two additional controllers: - fluxconfig-agent - fluxconfig-controller
These controllers have CRDs that define the version of Flux and any Flux Kustomizations that are managed via the Azure CLI.
The CRDs are all apiVersion: clusterconfig.azure.com/v1beta1.
The Kinds are: - FluxConfig - FluxConfigSyncStatus
The FluxConfig Kind configures Flux itself and creates any Kustomizations that refer to a single-source GitRepository. This guide assumes that this process is already completed and that a top-level Kustomization has been configured for the fleet repo cluster directory already set up at clusters/default/CLUSTER_NAME/manifests.
The CRDs that this FluxConfig generates are Flux CRDs, as follows: - GitRepositories - Kustomizations
These generated resources are viewable through Weave GitOps Enterprise.
Weave GitOps itself is deployed by Flux using a HelmRelease that pulls the Helm Chart. It doesn\u2019t need to install Flux, as it is assumed that Flux is already deployed. Therefore it can use the Azure Flux add-on, which poses no conflicts with WGE itself.
Incompatibilities exist between the Azure Flux add-on and CNCF Flux. They should not be run at the same time, on the same cluster, due to conflicts in the CRD management. If the Flux bootstrapping process IS run on a cluster with Azure Flux add-on, it will override the Azure Flux add-on with the Flux version used in the bootstrap. Also, it would add Flux manifests to the source Git repository. This would be undesirable.
Azure Flux add-on-enabled clusters keep the Azure Flux add-on in place.
"},{"location":"enterprise/join-cluster-azure-flux/#joining-a-cluster-to-wge","title":"Joining a Cluster to WGE","text":""},{"location":"enterprise/join-cluster-azure-flux/#setting-up-a-service-account","title":"Setting up a Service Account","text":"To join a cluster, you'll set up a service account with permissions and create a kubeconfig for the service account. This service account does not need cluster admin permissions unless you are bootstrapping Flux into the cluster. The bootstrapping process will either be A) carried out before joining the cluster to WGE; or B) configured specifically for Flux to be bootstrapped into the cluster from WGE.
If you already have Flux running, you can create the service account in your fleet repo:
apiVersion: v1\nkind: ServiceAccount\nmetadata:\nname: wgesa\nnamespace: default\n---\napiVersion: v1\nkind: Secret\ntype: kubernetes.io/service-account-token\nmetadata:\nname: wgesa-secret\nnamespace: default\nannotations:\nkubernetes.io/service-account.name: \"wgesa\"\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRoleBinding\nmetadata:\nname: impersonate-user-groups\nsubjects:\n- kind: ServiceAccount\nname: wgesa\nnamespace: default\nroleRef:\nkind: ClusterRole\nname: user-groups-impersonator\napiGroup: rbac.authorization.k8s.io\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRole\nmetadata:\nname: user-groups-impersonator\nrules:\n- apiGroups: [\"\"]\nresources: [\"users\", \"groups\"]\nverbs: [\"impersonate\"]\n- apiGroups: [\"\"]\nresources: [\"namespaces\"]\nverbs: [\"get\", \"list\"]\nKubernetes 1.24+ will not create secrets for Service Accounts for you, so you have to add it yourself.
You can also take care of this step in WGE's Secrets UI, setting up a a secret in SOPS or ESO.
Flux CRDs are compatible with the Azure Flux Configuration CRDs. This means that there are no compatibility issues between WGE and Azure Flux.
MSFT maintains CAPZ, the Azure CAPI provider. Currently there is no support for Azure Flux. A CAPI-based cluster will continue to run the Flux bootstrap process on cluster creation when managed by WGE, because there is no Azure Flux option.
"},{"location":"enterprise/join-cluster-azure-flux/#with-terraform-provider","title":"With Terraform Provider","text":"WGE uses TF-controller to deploy Terraform resources. For WGE to use the cluster as a target requires A) a resource created in the management cluster and B) a kubeconfig that maps to a service account in the target cluster. The Terraform cluster build typically creates this service account and then outputs to a secret store or local secret so that WGE can use it as a cluster. The Flux bootstrap process can be initiated directly with the Flux Terraform module, which deploys CNCF Flux to the target cluster.
Alternatively, you can apply an Azure Policy to provide the Azure Flux add-on. This is an example of how you can use the policy controls. This means you could come across clusters that are deployed with Terraform with the Azure Flux add-on already installed and would not run the Flux bootstrap process.
Either way, it is typical that Terraform-deployed clusters do not run the Flux bootstrap process at all, because it is usually already installed.
"},{"location":"enterprise/join-cluster-azure-flux/#with-crossplane","title":"With Crossplane","text":"The Azure Flux add-on is supported under Crossplane-deployed Azure clusters. Any clusters deployed with Crossplane that have the Azure Flux add-on enabled would also be added to WGE without running the bootstrap process.
"},{"location":"enterprise/releases-enterprise/","title":"Releases ENTERPRISE","text":"Info
This page details the changes for Weave GitOps Enterprise and its associated components. For Weave GitOps OSS, please see the release notes on GitHub.
"},{"location":"enterprise/releases-enterprise/#v0310","title":"v0.31.0","text":"2023-08-31
"},{"location":"enterprise/releases-enterprise/#highlights","title":"Highlights","text":"2023-08-17
"},{"location":"enterprise/releases-enterprise/#highlights_1","title":"Highlights","text":""},{"location":"enterprise/releases-enterprise/#ui","title":"UI","text":"2023-08-04
Warning
This release builds upon Weave GitOps v0.29.0 that has breaking changes from Flux v2.0.0. Please make sure that you read these release notes.
"},{"location":"enterprise/releases-enterprise/#dependency-versions_2","title":"Dependency versions","text":"2023-08-03
Danger
"},{"location":"enterprise/releases-enterprise/#breaking-changes","title":"\u26a0\ufe0f Breaking changes","text":"We introduced a breaking change in this release by upgrading to Flux v2 APIs, notably GitRepository v1, Kustomization v1, and Receiver v1. This means that this version of Weave GitOps Enterprise is not compatible with previous versions of Flux v2, such as v0.41.x and earlier.
Follow Flux or Weave GitOps to upgrade to Flux v2 GA before upgrading Weave GitOps Enterprise.
"},{"location":"enterprise/releases-enterprise/#highlights_2","title":"Highlights","text":""},{"location":"enterprise/releases-enterprise/#flux","title":"Flux","text":"2023-07-20
"},{"location":"enterprise/releases-enterprise/#highlights_3","title":"Highlights","text":"2023-07-07
"},{"location":"enterprise/releases-enterprise/#highlights_4","title":"Highlights","text":""},{"location":"enterprise/releases-enterprise/#explorer_2","title":"Explorer","text":"2023-06-22
"},{"location":"enterprise/releases-enterprise/#highlights_5","title":"Highlights","text":"2023-06-08
Bug fixes
"},{"location":"enterprise/releases-enterprise/#dependency-versions_7","title":"Dependency versions","text":"2023-05-25
"},{"location":"enterprise/releases-enterprise/#highlights_6","title":"Highlights","text":""},{"location":"enterprise/releases-enterprise/#gitopssets_2","title":"GitOpsSets","text":"(none)
"},{"location":"enterprise/releases-enterprise/#known-issues","title":"Known issues","text":""},{"location":"enterprise/releases-enterprise/#explorer_4","title":"Explorer","text":"2023-05-12
"},{"location":"enterprise/releases-enterprise/#highlights_7","title":"Highlights","text":""},{"location":"enterprise/releases-enterprise/#application-details","title":"Application Details","text":"2023-04-27
"},{"location":"enterprise/releases-enterprise/#highlights_8","title":"Highlights","text":""},{"location":"enterprise/releases-enterprise/#explorer_7","title":"Explorer","text":"2023-04-13
"},{"location":"enterprise/releases-enterprise/#highlights_9","title":"Highlights","text":"2023-03-30
"},{"location":"enterprise/releases-enterprise/#dependency-versions_12","title":"Dependency versions","text":"2023-03-16
"},{"location":"enterprise/releases-enterprise/#highlights_10","title":"Highlights","text":""},{"location":"enterprise/releases-enterprise/#ui_4","title":"UI","text":"2023-03-02
"},{"location":"enterprise/releases-enterprise/#highlights_11","title":"Highlights","text":""},{"location":"enterprise/releases-enterprise/#ui_5","title":"UI","text":"2023-02-16
"},{"location":"enterprise/releases-enterprise/#highlights_12","title":"Highlights","text":"This release contains dependency upgrades and bug fixes. For a larger list of updates, check out the Weave GitOps v0.17.0 release.
"},{"location":"enterprise/releases-enterprise/#v0160","title":"v0.16.0","text":"2023-02-02
"},{"location":"enterprise/releases-enterprise/#highlights_13","title":"Highlights","text":""},{"location":"enterprise/releases-enterprise/#create-external-secrets-via-wge-ui","title":"Create External Secrets via WGE UI","text":"No breaking changes
"},{"location":"enterprise/releases-enterprise/#v0151","title":"v0.15.1","text":"2023-01-19
"},{"location":"enterprise/releases-enterprise/#highlights_14","title":"Highlights","text":""},{"location":"enterprise/releases-enterprise/#multi-repository-support-weave-gitops-enterprise-adapts-and-scales-to-your-repository-structure","title":"Multi Repository support. Weave GitOps Enterprise adapts and scales to your repository structure","text":"No breaking changes
"},{"location":"enterprise/releases-enterprise/#v0141","title":"v0.14.1","text":"2023-01-05
"},{"location":"enterprise/releases-enterprise/#highlights_15","title":"Highlights","text":""},{"location":"enterprise/releases-enterprise/#secrets-management","title":"Secrets management","text":"[UI] \"Tenant\" is renamed to \"Workspace\" on details page.
[UI] Use time.RFC3339 format for all timestamps of the workspaces tabs.
"},{"location":"enterprise/releases-enterprise/#other","title":"Other","text":"[UI] Error notification boundary does not allow user to navigate away from the page.
[Gitops run] GitOps Run doesn't ask to install dashboard twice
"},{"location":"enterprise/releases-enterprise/#dependency-versions_17","title":"Dependency versions","text":"No breaking changes
"},{"location":"enterprise/releases-enterprise/#v0130","title":"v0.13.0","text":"2022-12-22
"},{"location":"enterprise/releases-enterprise/#highlights_16","title":"Highlights","text":""},{"location":"enterprise/releases-enterprise/#gitops-templates-path-feature","title":"GitOps Templates Path feature","text":"spec:\nresourcetemplates:\n- path: ./clusters/${CLUSTER_NAME}/definition/cluster.yaml\ncontent:\n- apiVersion: cluster.x-k8s.io/v1alpha4\nkind: Cluster\nmetadata:\nname: ${CLUSTER_NAME}\n...\n- apiVersion: infrastructure.cluster.x-k8s.io/v1alpha4\nkind: AWSCluster\nmetadata:\nname: ${CLUSTER_NAME}\n...\n- path: ./clusters/${CLUSTER_NAME}/workloads/helmreleases.yaml\ncontent:\n- apiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: ${CLUSTER_NAME}-nginx\n...\n- apiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: ${CLUSTER_NAME}-cert-manager\n...\n[UI] Notifications Fixed provider page showing a 404.
"},{"location":"enterprise/releases-enterprise/#dependency-versions_18","title":"Dependency versions","text":"No breaking changes
"},{"location":"enterprise/releases-enterprise/#v0120","title":"v0.12.0","text":"2022-12-09
"},{"location":"enterprise/releases-enterprise/#highlights_17","title":"Highlights","text":"We highly recommend users of v0.11.0 upgrade to this version as it includes fixes for a number of UI issues.
"},{"location":"enterprise/releases-enterprise/#gitops-templates_1","title":"GitOps Templates","text":"spec:\ncharts:\nitems:\n- chart: cert-manager\nversion: v1.5.3\neditable: false\nrequired: true\nvalues:\ninstallCRDs: ${CERT_MANAGER_INSTALL_CRDS}\ntargetNamespace: cert-manager\nlayer: layer-1\ntemplate:\ncontent:\nmetadata:\nlabels:\napp.kubernetes.io/name: cert-manager\nspec:\nretries: ${CERT_MANAGER_RETRY_COUNT}\nSupporting custom OIDC groups claims for azure/okta integration Support for OIDC custom username and group claims:
config\noidc:\nclaimUsername: \"\"\nclaimGroups: \"\"\nTerraform CRD Error Users of the Terraform Controller will be pleased to know we\u2019ve addressed the issue where an error would be displayed if it had not been installed on all connected clusters.
Management cluster renaming If the name of the cluster where Weave GitOps Enterprise is installed, was changed from the default of management through the config.cluster.name parameter, certain workflows could fail such as fetching profiles, this has now been resolved.
"},{"location":"enterprise/releases-enterprise/#dependency-versions_19","title":"Dependency versions\u200b","text":"weave-gitops v0.12.0 cluster-controller v1.4.1 cluster-bootstrap-controller v0.3.0 (optional) pipeline-controller v0.0.11 (optional) policy-agent 2.1.1
"},{"location":"enterprise/releases-enterprise/#known-issues_2","title":"Known issues","text":"2022-11-25
"},{"location":"enterprise/releases-enterprise/#highlights_18","title":"Highlights","text":""},{"location":"enterprise/releases-enterprise/#gitopstemplates","title":"GitOpsTemplates","text":"This release incorporates anonymous aggregate user behavior analytics to help us continuously improve the product. As an Enterprise customer, this is enabled by default. You can learn more about this here.
"},{"location":"enterprise/releases-enterprise/#dependency-versions_20","title":"Dependency versions","text":"We are making these changes to provide a unified and intuitive self-service experience within Weave GitOps Enterprise, removing misleading and potentially confusing terminology born from when only Clusters were backed by Templates.
New API Group for the GitOpsTemplate CRD - old: clustertemplates.weave.works - new: templates.weave.works
After upgrading Weave GitOps Enterprise which includes the updated CRD: 1. Update all your GitOpsTemplates in Git changing all occurrences of apiVersion: clustertemplates.weave.works/v1alpha1 to apiVersion: templates.weave.works/v1alpha1. 2. Commit, push and reconcile. They should now be viewable in the Templates view again. 3. Clean up the old CRD. As it stands: - kubectl get gitopstemplate -A will be empty as it is pointing to the old clustertemplates.weave.works CRD. - kubectl get gitopstemplate.templates.weave.works -A will work To fix the former of the commands, remove the old CRD (helm does not do this automatically for safety reasons): - kubectl delete crd gitopstemplates.clustertemplates.weave.works - You may have to wait up to 5 minutes for your local kubectl CRD cache to invalidate, then kubectl get gitopstemplate -A should be working as usual
Template Profiles / Applications / Credentials sections are hidden by default
For both CAPITemplates and GitopsTemplates the default visibility for all sections in a template has been set to \"false\". To re-enable profiles or applications on a template you can tweak the annotations
annotations:\ntemplates.weave.works/profiles-enabled: \"true\" # enable profiles\ntemplates.weave.works/kustomizations-enabled: \"true\" # enable applications\ntemplates.weave.works/credentials-enabled: \"true\" # enable CAPI credentials\nThe default values for a profile are not fetched and included in a pull-request
Prior to this release WGE would fetch the default values.yaml for every profile installed and include them in the HelmReleases in the Pull Request when rendering out the profiles of a template.
This was an expensive operation and occasionally led to timeouts.
The new behaviour is to omit the values and fall back to the defaults included in the helm-chart. This sacrifices some UX (being able to see all the defaults in the PR and tweak them) to improve performance. There should not be any final behaviour changes to the installed charts.
You can still view and tweak the values.yaml when selecting profiles to include on the \"Create resource (cluster)\" page. If changes are made here the updated values.yaml will be included.
2022-11-15
"},{"location":"enterprise/releases-enterprise/#highlights_19","title":"Highlights","text":"2022-11-10
"},{"location":"enterprise/releases-enterprise/#highlights_20","title":"Highlights","text":"2022-10-17
"},{"location":"enterprise/releases-enterprise/#highlights_21","title":"Highlights","text":"2022-09-22
"},{"location":"enterprise/releases-enterprise/#highlights_22","title":"Highlights","text":"If using the policy-agent included in the weave-gitops-enterprise helm chart, the configuration should now be placed under the config key.
old
policy-agent:\nenabled: true\naccountId: \"my-account\"\nclusterId: \"my-cluster\"\nnew
policy-agent:\nenabled: true\nconfig:\naccountId: \"my-account\"\nclusterId: \"my-cluster\"\nWarning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
As platform engineer or as developer, your applications and platform services will likely span multiple kubernetes clusters or infrastructure components. In order to manage and operate them you require a platform capability that allows you to discover the resources from a single place.
Explorer is that capability that allows any platform user to discover platform resources from a single place across all your kubernetes clusters.
"},{"location":"explorer/#faq","title":"FAQ","text":""},{"location":"explorer/#which-journeys-would-be-able-to-use-explorer-for","title":"Which journeys would be able to use explorer for?","text":"Explorer is better suited for journeys matching the discovery of resources across the platform resources inventory.
"},{"location":"explorer/#which-journeys-would-be-better-using-other-weave-gitops-capabilities-for","title":"Which journeys would be better using other weave gitops capabilities for?","text":"If you have a particular resources you want to manage, weave gitops offers single resource experience for almost every resource.
"},{"location":"explorer/#which-kinds-does-explorer-support","title":"Which Kinds does explorer support?","text":"Explorer support all Flux Applications and Sources CRDs
See Supported Kinds for more details.
"},{"location":"explorer/#next-steps","title":"Next Steps","text":"Now that you know what Explorer is, follow getting started to quickly have a feeling of what Explorer can do for you.
"},{"location":"explorer/configuration/","title":"Configuration ENTERPRISE","text":"Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
This page helps you to understand the options available to configure Explorer
"},{"location":"explorer/configuration/#prerequisites","title":"Prerequisites","text":"Before using Explorer, please ensure that: - You have Weave Gitops Enterprise v0.23.0
"},{"location":"explorer/configuration/#setup","title":"Setup","text":"The following configuration options are available for you to setup Explorer.
You should specify them in your HelmRelease values:
---\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: weave-gitops-enterprise\nnamespace: flux-system\nspec:\n# ... other spec components\nvalues:\nenableExplorer: true # feature flag to enable explorer\nuseQueryServiceBackend: true # uses explorer query backend in collection UIs\nexplorer:\ncollector:\nserviceAccount: # service account that collector will impersonate in leaf clusters\nname: collector\nnamespace: flux-system\nExplorer watches the GitopsClusters that you have connected to Weave Gitops Enterprise, as well as your Management cluster.
"},{"location":"explorer/configuration/#kinds","title":"Kinds","text":"Explorer watches for the following kind resources out of the box:
Flux GitOps Toolkit
Weave Gitops - GitopsSets - Templates - Policy Audit Violations
"},{"location":"explorer/configuration/#data-layer","title":"Data Layer","text":"Explorer take a simple approach to manage resource views. It leverages a Data Store for caching the views and query them. The storage lifecycle is bounded to Weave Gitops Enterprise app and does not provide persistence guarantees. Instead, it requests data as required to the leaf clusters. In its simplest form, the data store used is SQLite.
"},{"location":"explorer/configuration/#authentication-and-authorization","title":"Authentication and Authorization","text":"There are two main paths to consider within Explorer in the context of authentication and authorization (authN/authZ):
We look into them separately.
"},{"location":"explorer/configuration/#authentication-and-authorization-for-querying","title":"Authentication and Authorization for querying","text":"Explorer leverages existing authentication and authorization built-in the application. It identifies for a user logged in the application: its identity and the access permissions via Kuberentes RBAC. Query results are filtered honouring the access determined via RBAC.
"},{"location":"explorer/configuration/#authentication-and-authorization-for-collecting","title":"Authentication and Authorization for collecting","text":"GitopsClusters define the connection and security context that Explorer leverages to collect data from leaf clusters. Given that you have followed the indications in setup RBAC, the GitopsCluster service account is able to impersonate any user or group.
Tip
Collector RBAC resources are part of your leaf clusters common RBAC configuration. It is commonly located in your clusters/bases folder, as described in Getting started.
To configure collection, you would need to extend this configuration with the following:
apiVersion: v1\nkind: ServiceAccount\nmetadata:\nname: collector # should match .spec.values.explorer.collector.serviceAccount.name\nnamespace: flux-system # should match .spec.values.explorer.collector.serviceAccount.namespace\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRole\nmetadata:\nname: collector # could be .spec.values.explorer.collector.serviceAccount.name\nrules:\n- apiGroups: [ \"rbac.authorization.k8s.io\" ]\nresources: [ \"roles\", \"clusterroles\", \"rolebindings\", \"clusterrolebindings\" ]\nverbs: [ \"list\", \"watch\" ]\n- apiGroups: [ \"kustomize.toolkit.fluxcd.io\" ]\nresources: [ \"kustomizations\" ]\nverbs: [ \"list\", \"watch\" ]\n- apiGroups: [ \"helm.toolkit.fluxcd.io\" ]\nresources: [ \"helmreleases\" ]\nverbs: [ \"list\", \"watch\" ]\n- apiGroups: [ \"source.toolkit.fluxcd.io\" ]\nresources: [ \"buckets\", \"helmcharts\", \"gitrepositories\", \"helmrepositories\", \"ocirepositories\" ]\nverbs: [ \"list\", \"watch\" ]\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRoleBinding\nmetadata:\nname: collector # could be .spec.values.explorer.collector.serviceAccount.name\nsubjects:\n- kind: ServiceAccount\nname: collector # should match .spec.values.explorer.collector.serviceAccount.name\nnamespace: flux-system # should match .spec.values.explorer.collector.serviceAccount.namespace\nroleRef:\nkind: ClusterRole\nname: collector # name of the cluster role created earlier\napiGroup: rbac.authorization.k8s.io\nIf you want the collector to watch a particular namespace use a RoleBinding instead.
apiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRole\nmetadata:\nname: clusters-service-impersonator-role\nrules:\n- apiGroups: [\"\"]\nresources: [\"users\", \"groups\"]\nverbs: [\"impersonate\"]\n- apiGroups: [ \"\" ]\nresources: [ \"serviceaccounts\" ]\nverbs: [ \"impersonate\" ]\nresourceNames:\n- \"collector\" # should match .spec.values.explorer.collector.serviceAccount.name\nWarning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
This guide shows you the basics steps to start using Explorer.
"},{"location":"explorer/getting-started/#pre-requisites","title":"Pre-requisites","text":"Before using Explorer, please ensure that:
Explorer is enabled via configuration through the feature flag explorer.enabled that you could configure in your Weave Gitops Enterprise HelmRelease values:
---\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: weave-gitops-enterprise\nnamespace: flux-system\nspec:\n# ... other spec components\nvalues:\nexplorer:\nenabled: true # global enable/disable flag\ncollector:\n# ServiceAccount that explorer will use to watch clusters for resources\nserviceAccount:\nname: \"collector\"\nnamespace: \"flux-system\"\ncleaner:\ndisabled: false\nenabledFor: # controls which parts of the UI utilize the Explorer UI/Server components\n- applications\n- sources\n- gitopssets\n- templates\nThe enabledFor field will control which parts of the UI utilize the Explorer backend for performant queries. Note that this does not control the collection of these objects, only the presentation of the objects in the UI.
For a complete overview on the configuration you could see configuration.
"},{"location":"explorer/getting-started/#explorer-ui","title":"Explorer UI","text":"Login to Weave Gitops and Explorer will be shown in the navigation menu Explorer.
Explorer UI looks as follows:
It has two main components:
For a more detailed view on the UI you could see querying.
"},{"location":"explorer/operations/","title":"Operations ENTERPRISE","text":"Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
As platform engineer you could need to have a finer understanding on the underlying logic for Explorer. The following options are available to you to operate and troubleshoot it.
"},{"location":"explorer/operations/#debug-access-rules","title":"Debug Access Rules","text":"It is a debugging tool to make visible explorer authorization logic. You could find it as tab Access Rules alongside the Query tab.
You could discover by Cluster and Subject the Kinds it is allowed to read. These are the rules that will be the source of truth doing authorization when a user does a query.
Explorer provides the following telemetry to use for operations.
"},{"location":"explorer/operations/#metrics","title":"Metrics","text":"Explorer exports Prometheus metrics. See setup to get started.
"},{"location":"explorer/operations/#querying","title":"Querying","text":"Explorer querying path is composed of three components exporting metrics:
Based on go-http-metrics, the following metrics are generated.
Request Duration: histogram with the latency of the HTTP requests.
http_request_duration_seconds_bucket{handler=\"/v1/query\",method=\"POST\",le=\"0.05\"} 0\nhttp_request_duration_seconds_sum{handler=\"/v1/query\",method=\"POST\"} 10.088081923\nhttp_request_duration_seconds_count{handler=\"/v1/query\",method=\"POST\"} 51\nResponse Size: histogram with the size of the HTTP responses in bytes
http_response_size_bytes_bucket{handler=\"/v1/query\",method=\"POST\",le=\"0.05\"} 10\nhttp_response_size_bytes_sum{handler=\"/v1/query\",method=\"POST\"} 120\nhttp_response_size_bytes_count{handler=\"/v1/query\",method=\"POST\"} 10\nRequests In Flight: gauge with the number of inflight requests being handled at the same time.
http_requests_inflight{handler=\"/v1/query\"} 0\nRequest Latency: histogram with the latency of the datastore read requests.
datastore_latency_seconds_bucket{action=\"GetObjectByID\", le=\"+Inf\", status=\"success\"} 1175\ndatastore_latency_seconds_bucket{action=\"GetObjectByID\", le=\"0.01\", status=\"success\"} 1174\ndatastore_latency_seconds_count{action=\"GetObjectByID\", status=\"success\"} 1175\ndatastore_latency_seconds_count{action=\"GetRoleBindings\", status=\"success\"} 47\ndatastore_latency_seconds_count{action=\"GetRoles\", status=\"success\"} 47\ndatastore_latency_seconds_sum{action=\"GetObjectByID\", status=\"success\"} 0.6924557999999995\ndatastore_latency_seconds_sum{action=\"GetRoleBindings\", status=\"success\"} 1.329158916\ndatastore_latency_seconds_sum{action=\"GetRoles\", status=\"success\"} 3.942473879999999\nRequests In Flight: gauge with the number of inflight requests being handled at the same time.
datastore_inflight_requests{action=\"GetObjectByID\"} 0\ndatastore_inflight_requests{action=\"GetRoleBindings\"} 0\ndatastore_inflight_requests{action=\"GetRoles\"} 0\nRequest Latency: histogram with the latency of the indexer read requests.
indexer_latency_seconds_bucket{action=\"ListFacets\", le=\"+Inf\", status=\"success\"} 1\nindexer_latency_seconds_bucket{action=\"Search\", le=\"+Inf\", status=\"success\"} 47\nindexer_latency_seconds_sum{action=\"ListFacets\", status=\"success\"} 0.008928666\nindexer_latency_seconds_sum{action=\"Search\", status=\"success\"} 0.06231312599999999\nindexer_latency_seconds_count{action=\"ListFacets\", status=\"success\"} 1\nindexer_latency_seconds_count{action=\"Search\", status=\"success\"} 47\nRequests In Flight: gauge with the number of inflight requests being handled at the same time.
indexer_inflight_requests{action=\"ListFacets\"} 0\nindexer_inflight_requests{action=\"Search\"} 0\nExplorer collecting path is composed of three components exporting metrics:
The following metrics are available to monitor its health.
"},{"location":"explorer/operations/#cluster-watcher","title":"Cluster Watcher","text":"The metric collector_cluster_watcher provides the number of the cluster watchers it the following status: - Starting: a cluster watcher is starting at the back of detecting that a new cluster has been registered. - Started: cluster watcher has been started and collecting events from the remote cluster. This is the stable state. - Stopping: a cluster has been deregistered so its cluster watcher is no longer required. In the process of stopping it. - Failed: a cluster watcher has failed during the creation or starting process and cannot collect events from the remote clusters. This is the unstable state.
Where collector is the type of collector, it could be - rbac: for collecting RBAC resources (ie roles) - objects: for collecting non-rbac resources (ie kustomizations)
collector_cluster_watcher{collector=\"objects\", status=\"started\"} 1\ncollector_cluster_watcher{collector=\"objects\", status=\"starting\"} 0\ncollector_cluster_watcher{collector=\"rbac\", status=\"started\"} 1\ncollector_cluster_watcher{collector=\"rbac\", status=\"starting\"} 0\nA sum on collector_cluster_watcher gives the total number of cluster watchers that should be equal to the number of clusters
Request Latency: histogram with the latency of the datastore write requests.
datastore_latency_seconds_bucket{action=\"StoreRoles\", le=\"+Inf\", status=\"success\"} 1175\ndatastore_latency_seconds_bucket{action=\"StoreRoles\", le=\"0.01\", status=\"success\"} 1174\ndatastore_latency_seconds_count{action=\"StoreRoles\", status=\"success\"} 1175\ndatastore_latency_seconds_count{action=\"DeleteRoles\", status=\"success\"} 47\ndatastore_latency_seconds_count{action=\"DeleteAllRoleBindings\", status=\"success\"} 47\ndatastore_latency_seconds_sum{action=\"StoreRoles\", status=\"success\"} 0.6924557999999995\ndatastore_latency_seconds_sum{action=\"DeleteRoles\", status=\"success\"} 1.329158916\ndatastore_latency_seconds_sum{action=\"DeleteAllRoleBindings\", status=\"success\"} 3.942473879999999\nRequests In Flight: gauge with the number of inflight write requests being handled at the same time.
datastore_inflight_requests{action=\"StoreRoles\"} 0\ndatastore_inflight_requests{action=\"StoreRoleBindings\"} 0\ndatastore_inflight_requests{action=\"DeleteAllRoleBindings\"} 0\nRequest Latency: histogram with the latency of the indexer write requests.
indexer_latency_seconds_bucket{action=\"Add\",status=\"success\",le=\"+Inf\"} 109\nindexer_latency_seconds_bucket{action=\"Remove\",status=\"success\",le=\"+Inf\"} 3\nindexer_latency_seconds_sum{action=\"Add\",status=\"success\"} 8.393912168\nindexer_latency_seconds_sum{action=\"Remove\",status=\"success\"} 0.012298476\nindexer_latency_seconds_count{action=\"Add\",status=\"success\"} 109\nindexer_latency_seconds_count{action=\"Remove\",status=\"success\"} 3\nRequests In Flight: gauge with the number of inflight requests being handled at the same time.
indexer_inflight_requests{action=\"Add\"} 0\nindexer_inflight_requests{action=\"Remove\"} 0\nUse Explorer dashboard to monitor its golden signals
Explorer dashboard is part of Weave GitOps Dashboards
"},{"location":"explorer/querying/","title":"Querying ENTERPRISE","text":"Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
Explorer recommended way to discover resources is via its search dialog. This guide provides the background to understand it and set how to use it.
"},{"location":"explorer/querying/#schema","title":"Schema","text":"Every resource is normalised to the following common schema:
Key Description Cluster Name of cluster where the resource exists. As gitops cluster<GitopsClusterNamespace,GitopsClusterName> Namespace Namespace name where the resource exists. Kind Resource kubernetes type or kind Name Resource name as specified in its manifest. Status Resource health status. Indicates the status of its reconciliation. Message Resource health status message. It extends status field with information about the status. For a podinfo helm release from a cluster default/progress-delivery-demo2-32 like this:
apiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: podinfo\nnamespace: flux-system\nspec:\nchart:\nspec:\nchart: podinfo\ninterval: 1m\nreconcileStrategy: ChartVersion\nsourceRef:\nkind: HelmRepository\nname: podinfo\nversion: 6.0.0\ninterval: 1m\nstatus:\nconditions:\n- message: Release reconciliation succeeded\nreason: ReconciliationSucceeded\nstatus: \"True\"\ntype: Ready\nThe schema looks like
Cluster Namespace Kind Name Status Messagedefault/progress-delivery-demo2-32 flux-system HelmRelease podinfo Success Release reconciliation succeeded You can open the query filter settings by clicking on the filter button:
"},{"location":"explorer/querying/#filtering-and-searching","title":"Filtering and Searching","text":"The Search field allows for free-form text entry to query objects across all fields. For example, if we enter the term \"podinfo\", we will get matches for not only object names, but also strings from the Message field:
To filter the results by cluster, kind, namespace, enable the checkbox filters:
Note that the free-form terms only apply to the filtered results from the kind filter. In this case, we only match the \"podinfo\" string on results that are Kustomizations.
We can also \"OR\" filters together. Note that filters within a category are OR'd together, but terms are AND'd across categories. For example, selecting the Kind=Kustomization and Kind=HelmRelease filters will show both Kustomizations and HelmReleases:
A GitOpsTemplate enables application developers to self-service components and services easily through the Weave GitOps Dashboard. It's a simple YAML file that you can enrich with parameters, variables, metadata, and conditions.
Use a GitOpsTemplate to template any resource that can be expressed in YAML (basic Kubernetes resources, Flux primitives, Terraform controller, Crossplane, Cluster API, etc.) into a standardised definition.
Application developers can use a template through our GUI. The rendered template is added to their GitOps repository via a pull request. When merged and reconciled, the resources in the template are created. A resource can be a MachinePool for CAPI objects, a Flux Kustomization, or a Terraform Controller resource, to name a few examples.
Tip
A GitOpsTemplate must be valid yaml. Beyond this, a rendered template can create any resource you need .
Info
GitOpsTemplate or CAPITemplate?
The only difference between CAPITemplate and GitOpsTemplate is the default value of these two annotations:
CAPITemplate default value for GitOpsTemplate templates.weave.works/add-common-bases \"true\" \"false\" templates.weave.works/inject-prune-annotations \"true\" \"false\""},{"location":"gitops-templates/annotations/","title":"Annotations ENTERPRISE","text":""},{"location":"gitops-templates/annotations/#the-add-common-bases-annotation","title":"The add-common-bases annotation","text":"The templates.weave.works/add-common-bases: \"true\" annotation can be used to enable and disable the addition of a \"common bases\" Kustomization to the list of rendered files. This kustomization will sync a path that is common to all clusters (clusters/bases).
An example usecase would be to ensure that certain RBAC or policies are applied to all clusters using this template.
"},{"location":"gitops-templates/annotations/#the-inject-prune-annotation-annotation","title":"Theinject-prune-annotation annotation","text":"The templates.weave.works/inject-prune-annotation: \"true\" annotation can be used to enable and disable the injection of Flux's prune annotation into certain resources.
When enabled, GitOps automatically injects a kustomize.toolkit.fluxcd.io/prune: disabled annotation into every resource in the spec.resourcetemplates that is not a cluster.x-k8s.io.Cluster and not a gitops.weave.works.GitopsCluster.
The intention here is stop Flux from explicitly deleting subresources of the Cluster like AWSCluster, KubeadmControlPlane, AWSMachineTemplate etc and let the CAPI controllers handle their removal.
This is the pattern recommended in the capi-quickstart guide https://cluster-api.sigs.k8s.io/user/quick-start.html#clean-up.
"},{"location":"gitops-templates/cli/","title":"Template CLI ENTERPRISE","text":"The Enterprise gitops CLI tool provides a set of commands to help you manage your templates.
Here we're going to talk about the gitops create template command that allows you to render templates locally and airgapped, without a full WGE installation in a Kubernetes cluster.
The gitops create template command only works with GitOpsTemplate objects. It does not work with CAPITemplate objects. You should be able to migrate any CAPITemplate objects to GitOpsTemplate with some small tweaks.
Info
GitOpsTemplate or CAPITemplate?
The only difference between CAPITemplate and GitOpsTemplate is the default value of these two annotations:
CAPITemplate default value for GitOpsTemplate templates.weave.works/add-common-bases \"true\" \"false\" templates.weave.works/inject-prune-annotations \"true\" \"false\""},{"location":"gitops-templates/cli/#installation","title":"Installation","text":"See the Weave Gitops Enterprise installation instructions for details on how to install the EE gitops CLI tool.
Using a local GitOpsTemplate manifest with required parameters exported in the environment, the command can render the template to one of the following: 1. The current kubecontext directly (default) 1. stdout with --export 1. The local file system with --output-dir, this will use the spec.resourcestemplates[].path fields in the template to determine where to write the rendered files. This is the recommended approach for GitOps as you can then commit the rendered files to your repository.
gitops create template \\\n--template-file capd-template.yaml \\\n--output-dir ./clusters/ \\\n--values CLUSTER_NAME=foo\nAs in the UI you can add profiles to your template. However instead of reading the latest version of a profile and its layers from a HelmRepository object in the cluster, we instead read from your local helm cache.
helm repo add weaveworks-charts https://raw.githubusercontent.com/weaveworks/weave-gitops-profile-examples/gh-pages\nhelm repo update\nThis particular helm repo provides a version of the cert-manager repo and others.
You can supply a values.yaml file to a profile using the values parameter. For example we can supply cert-manager's values.yaml with:
gitops create template \\\n--template-file capd-template.yaml \\\n--output-dir ./out \\\n--values CLUSTER_NAME=foo \\\n--profiles \"name=cert-manager,namespace=foo,version=>0.1,values=cert-manager-values.yaml\"\nInstead of specifying the parameters on the command line you can supply a config file. For example the above invocation can be replaced like so:
```yaml title=config.yaml template-file: capd-capi-template.yaml output-dir: ./out values: - CLUSTER_NAME=foo profiles: - name=cert-manager,namespace=foo,version=>0.1,values=cert-manager-values.yaml
and executed with:\n\n```bash\ngitops create template --config config.yaml\nGitOps template objects need to be wrapped with the GitOpsTemplate custom resource and then loaded into the management cluster.
apiVersion: templates.weave.works/v1alpha2\nkind: GitOpsTemplate\nmetadata:\nname: cluster-template-development\nlabels:\nweave.works/template-type: cluster\nspec:\ndescription: This is the std. CAPD template\nrenderType: templating\nparams:\n- name: CLUSTER_NAME\ndescription: This is used for the cluster naming.\nresourcetemplates:\n- apiVersion: cluster.x-k8s.io/v1alpha3\nkind: Cluster\nmetadata:\nname: \"{{ .params.CLUSTER_NAME }}\"\nTip
For complete examples of widely-used templates, see the Quickstart guide.
GitOps Templates were originally introduced to enable self-service operations for the the cluster creation workflow.
We have since extended this capability to cover Terraform, Crossplane and general Kubernetes resources.
An example template could, upon merging to a GitOps repository and reconciling in a cluster, provide a running developer environment consisting of an EKS cluster, an RDS database, and a branch and revision of the current application through single template.
Templates can be loaded into the cluster by Platform Operator by adding them to the Flux-manage GitOps repository for the target cluster. Alternatively, they can be applied directly to the cluster with kubectl.
Info
Weave GitOps will search for templates in the default namespace. This can be changed by configuring the config.capi.namespace value in the Weave GitOps Enterprise Helm Chart.
Template types are used by Weave GitOps to group the templates nicely in the Dashboard UI.
There are 4 recommended template types:
Declare this in the object manifest by using the weave.works/template-type label and setting the value as the name of the type.
---\napiVersion: templates.weave.works/v1alpha2\nkind: GitOpsTemplate\nmetadata:\nname: example-template\nnamespace: default\nlabels:\nweave.works/template-type: pipeline\nspec:\n# ...\nThe rendering of certain component sections in a template can be enabled or disabled with annotations. The annotation keys are of the form templates.weave.works/COMPONENT-enabled and have boolean values.
Supported components:
Example:
annotations:\ntemplates.weave.works/profiles-enabled: \"true\"\ntemplates.weave.works/kustomizations-enabled: \"false\"\ntemplates.weave.works/credentials-enabled: \"true\"\nWhen rendering a template, a templates.weave.works/create-request annotation is added by default to the first resource in the resourcetemplates.
It can be added to any other resource by simply adding the annotation in empty form. This annotation holds information about which template generated the resource and the parameter values used as a json string.
If the resource type is one of the following and has this annotation, an Edit resource button will appear in the GitOps UI which allows the editing of the resource by users, after which it will be re-rendered:
Example:
spec:\nresourcetemplates:\n- apiVersion: v1\nkind: ConfigMap\nmetadata:\nname: my-configmap\ndata:\nmy-key: my-value\n- apiVersion: source.toolkit.fluxcd.io/v1beta1\nkind: HelmRepository\nmetadata:\n# This annotation will add an `Edit resource` button in the UI for this resource\nannotations:\ntemplates.weave.works/create-request: ''\nname: nginx\nnamespace: default\nWhen users have chosen a template, they will be presented with a form to complete.
This form will collect the specific resource configuration which they would like applied to their instance.
Resource variables, or parameters, are set by the template author in the template object manifest under spec.params.
Some params are required for all resources as they will be used to generate paths for the eventually rendered resources.
These are: - CLUSTER_NAME - RESOURCE_NAME
The following metadata fields can be added for each parameter under spec.params. These will get rendered nicely in the UI form allowing users to understand what each field is for.
Example:
spec:\nparams:\n- name: IP_ADDRESS\ndescription: 'The IP address of this service'\noptions: [1.2.3.4, 5.6.7.8]\ndefault: 1.2.3.4\nProfiles are enhanched Helm Charts which allow operators to make additional components either optional or required to developers using self-service templates.
Default and required profiles can be added via the template spec.charts section.
spec:\ncharts:\nitems:\n- name: nginx\nversion: 1.0.0\ntargetNamespace: nginx\n- name: cert-manager\ntargetNamespace: cert-manager\nA template with the above profiles would offer Application Developers the option to add nginx and cert-manager resources to their templated resources, ready for deployment to their cluster.
Keys available in the spec.charts section and the template variables available to them.
helmRepositoryTemplate.path Path the HelmRepository will be written to params items list of charts to configure, see below Keys available in the spec.charts.items entries and the template variables available to them.
template.content Full or partial HelmRelease CR template params template.path Path the HelmRelease will be written to params chart Shortcut to HelmRelease.spec.chart.spec.chart version Shortcut to HelmRelease.spec.chart.spec.version targetNamespace Shortcut to HelmRelease.spec.targetNamespace values Shortcut to HelmRelease.spec.values params layer Layer to install as required (default=false) Allow the user to de-select this profile editable (default=false) Allow the user to edit the values.yaml of this profile Expand for a complete yaml example spec:\ncharts:\nhelmRepositoryTemplate:\npath: clusters/${CLUSTER_NAME}/helm-repositories.yaml\nitems:\n- chart: cert-manager\nversion: v1.5.3\neditable: false\nrequired: true\nvalues:\ninstallCRDs: ${CERT_MANAGER_INSTALL_CRDS}\ntargetNamespace: cert-manager\nlayer: layer-1\ntemplate:\npath: clusters/${CLUSTER_NAME}/cert-manager.yaml\ncontent:\nmetadata:\nlabels:\napp.kubernetes.io/name: cert-manager\nspec:\nretries: ${CERT_MANAGER_RETRY_COUNT}\nTip
template.content will be merged over the top of a default HelmRelease CR so it does not need to be complete.
Deprecated feature
Where possible please use the spec.charts section as detailed above to declare profiles.
Profiles can also be included within templates by the capi.weave.works/profile-INDEX annotation.
annotations:\ncapi.weave.works/profile-0: '{\"name\": \"NAME\", \"version\": \"VERSION\", \"editable\": EDITABLE, \"namespace\": \"NAMESPACE\"}'\nWhere:
Quickstart templates are GitOpsTemplates that you could use when getting started with Weave Gitops Enterprise It aims to provide a simplified basic experience.
The templates exist as a Helm Chart in the weave-gitops-quickstart github repo.
To get started, add the following HelmRelease object to your Weave GitOps Enterprise configuration repo for your management cluster.
---\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: GitRepository\nmetadata:\nname: weave-gitops-quickstart\nnamespace: flux-system\nspec:\ninterval: 10m0s\nref:\nbranch: main\nurl: https://github.com/weaveworks/weave-gitops-quickstart\n---\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: quickstart-templates\nnamespace: flux-system\nspec:\nchart:\nspec:\nchart: \"quickstart-templates\"\nversion: \">=0.1.0\"\nsourceRef:\nkind: GitRepository\nname: weave-gitops-quickstart\nnamespace: flux-system\ninterval: 10m0s\nCommit and merge the above file. Once the HelmRelease has been successfully deployed to your cluster, navigate to your Weave GitOps UI Dashboard. You will see that the templates Chart is now deployed to your cluster.
If you click on the Templates tab in the sidebar, you will see the Quickstart templates are now available for use:
The following pipeline templates have been made available on your Weave GitOps Enterprise instance:
GitOpsTemplates as a Platform Engineer","text":"The above Quickstart templates are designed to provide a practical getting started experience. We encourage Platform Operators to start off with these templates within their team to ramp up on using Weave GitOps.
If the need arises later, operators can always expand on these templates to develop their own set of self-service capabilities.
"},{"location":"gitops-templates/quickstart-templates/#using-gitopstemplates-as-an-application-developer","title":"UsingGitOpsTemplates as an Application Developer","text":"As a developer using Weave GitOps Enterprise, use the templates to explore GitOps's capabilities. For example, to create a pipeline for your application: use the above template provided by your Operations team to create required resources. Once they have been added to your GitOps repository, you can adapt the rendered resources to meet your needs.
Want to contribute?
The Quickstart templates are maintained by the Weave Gitops team. If you would like to make alterations, suggest fixes, or even contribute a new template which you find cool, just head to the repo and open a new issue or PR!
"},{"location":"gitops-templates/repo-rendered-paths/","title":"Rendered Template Paths ENTERPRISE","text":"Template authors can configure the eventual locatation of the rendered template in the user's GitOps repository.
This allows for more control over where different resources in the template are rendered.
"},{"location":"gitops-templates/repo-rendered-paths/#configuring-paths","title":"Configuring Paths","text":"The path for rendered resources is configured via the spec.resourcetemplates[].path field.
Important to note
spec:\nresourcetemplates:\n// highlight-next-line\n- path: clusters/${CLUSTER_NAME}/definition/cluster.yaml\ncontent:\n- apiVersion: cluster.x-k8s.io/v1alpha4\nkind: Cluster\nmetadata:\nname: ${CLUSTER_NAME}\n...\n- apiVersion: infrastructure.cluster.x-k8s.io/v1alpha4\nkind: AWSCluster\nmetadata:\nname: ${CLUSTER_NAME}\n...\n// highlight-next-line\n- path: clusters/${CLUSTER_NAME}/workloads/helmreleases.yaml\ncontent:\n- apiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: ${CLUSTER_NAME}-nginx\n...\n- apiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: ${CLUSTER_NAME}-cert-manager\n...\ncharts","text":"The spec.charts.helmRepositoryTemplate.path and spec.charts.items[].template.path fields can be used to specify the paths of these resources:
Example
spec:\ncharts:\nhelmRepositoryTemplate:\n// highlight-next-line\npath: clusters/${CLUSTER_NAME}/workloads/helm-repo.yaml\nitems:\n- chart: cert-manager\nversion: 0.0.8\ntemplate:\n// highlight-next-line\npath: clusters/${CLUSTER_NAME}/workloads/cert-manager.yaml\nIf the spec.resourcetemplates[].path is omitted, a default path for the rendered template is calculated.
In this case some of the submitted params are used. Users must provide one of the following parameters: - CLUSTER_NAME - RESOURCE_NAME
To ensure users supply these values, set the parameters to required in the the template definition:
spec:\nparams:\n- name: RESOURCE_NAME\nrequired: true\n# or\n- name: CLUSTER_NAME\nrequired: true\nImportant
The kustomization feature and the add-common-bases annotation feature always use a calculated default path. If you are using these features one of CLUSTER_NAME or RESOURCE_NAME must be provided, even if you specify a path for all the other resources in the template.
The default path for a template has a few components: - From the params: CLUSTER_NAME or RESOURCE_NAME, required. - From the params: NAMESPACE, default: default - From values.yaml for the Weave GitOps Enterprise mccp chart: values.config.capi.repositoryPath, default: clusters/management/clusters
These are composed to create the path: ${repositoryPath}/${NAMESPACE}/${CLUSTER_OR_RESOURCE_NAME}.yaml
Using the default values and supplying CLUSTER_NAME as my-cluster will result in the path: clusters/management/clusters/default/my-cluster.yaml
Resource templates are used to create Kubernetes resources. They are defined in the spec.resourcetemplates section of the template.
content key","text":"The content key is used to define a list of resources:
spec:\nresourcetemplates:\n- content:\n- apiVersion: v1\nkind: Namespace\nmetadata:\nname: nginx\n- apiVersion: v1\nkind: Namespace\nmetadata:\nname: cert-manager\nraw key","text":"The raw key is used to define a raw string that will written to the specified path.
This can be useful to preserve comments or formatting in the rendered resource.
spec:\nresourcetemplates:\n- path: \"helm-release.yaml\"\nraw: |\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: podinfo\nnamespace: prod-github\nspec:\ninterval: 1m\nchart:\nspec:\nchart: podinfo\nversion: \"6.0.0\" # {\"$promotion\": \"flux-system:podinfo-github:prod\"}\nsourceRef:\nkind: HelmRepository\nname: podinfo\ninterval: 1m\nInfo
The following templating languages are supported: - envsubst (default) - templating
Declare the templating language to be used to render the template by setting spec.renderType.
envsubst, which is short for 'environment substitution', uses envsubst for rendering. This templating format is used by clusterctl.
Variables can be set for rendering into the template in the ${VAR_NAME} syntax.
${var} Value of $var ${#var} String length of $var ${var^} Uppercase first character of $var ${var^^} Uppercase all characters in $var ${var,} Lowercase first character of $var ${var,,} Lowercase all characters in $var ${var:n} Offset $var n characters from start ${var:n:len} Offset $var n characters with max length of len ${var#pattern} Strip shortest pattern match from start ${var##pattern} Strip longest pattern match from start ${var%pattern} Strip shortest pattern match from end ${var%%pattern} Strip longest pattern match from end ${var-default} If $var is not set, evaluate expression as $default ${var:-default} If $var is not set or is empty, evaluate expression as $default ${var=default} If $var is not set, evaluate expression as $default ${var:=default} If $var is not set or is empty, evaluate expression as $default ${var/pattern/replacement} Replace as few pattern matches as possible with replacement ${var//pattern/replacement} Replace as many pattern matches as possible with replacement ${var/#pattern/replacement} Replace pattern match with replacement from $var start ${var/%pattern/replacement} Replace pattern match with replacement from $var end"},{"location":"gitops-templates/supported-langs/#templating","title":"Templating","text":"Templating uses text/templating for rendering, using go-templating style syntax {{ .params.CLUSTER_NAME }} where params are provided by the .params variable. Template functions can also be used with the syntax {{ .params.CLUSTER_NAME | FUNCTION }}.
As taken (from the Sprig library)
Function Type Functions String Functions trim, wrap, randAlpha, plural String List Functions splitList, sortAlpha Integer Math Functions add, max, mul Integer Slice Functions until, untilStep Float Math Functions addf, maxf, mulf Date Functions now, date Defaults Functions default, empty, coalesce, fromJson, toJson, toPrettyJson, toRawJson, ternary Encoding Functions b64enc, b64dec Lists and List Functions list, first, uniq Dictionaries and Dict Functions get, set, dict, hasKey, pluck, dig, deepCopy Type Conversion Functions atoi, int64, toString Flow Control Functions fail UUID Functions uuidv4 Version Comparison Functions semver, semverCompare Reflection typeOf, kindIs, typeIsLike"},{"location":"gitops-templates/supported-langs/#custom-delimiters","title":"Custom Delimiters","text":"The default delimiters for renderType: templating are {{ and }}. These can be changed by setting the templates.weave.works/delimiters annotation on the template. For example:
There are now multiple published versions of the template CRD.
"},{"location":"gitops-templates/versions/#migration-notes","title":"Migration notes","text":""},{"location":"gitops-templates/versions/#v1alpha1-to-v1alpha2","title":"v1alpha1 to v1alpha2","text":"When manually migrating a template from v1alpha1 to v1alpha2 (for example in git) you will need to: 1. Update the apiVersion: 1. for GitopsTemplate update the apiVersion to templates.weave.works/v1alpha2 1. for CAPITemplate update the apiVersion to capi.weave.works/v1alpha2 1. Move the spec.resourcetemplates field to spec.resourcetemplates[0].content 1. Either leave the spec.resourcetemplates[0].path field empty or give it a sensible value.
If you experience issues with the path not being recognised when Flux reconciles the new template versions, try manually applying the new template to the cluster directly with: 1. Run kubectl apply -f capi-template.yaml 1. Run flux reconcile kustomization --with-source flux-system twice.
As of Weave Gitops Enterprise 0.28.0 the conversion webhook has been removed.
This removed the need for cert-manager to be installed, but you will now have to convert any v1alpha1 templates to v1alpha2 manually in git.
v1alpha2 (default) notes","text":"This version changes the type of spec.resourcetemplates from a list of objects to a list of files with a path and content:
Example:
spec:\nresourcetemplates:\n- path: \"clusters/{{ .params.CLUSTER_NAME }}.yaml\"\ncontent:\n- apiVersion: cluster.x-k8s.io/v1alpha3\nkind: Cluster\nmetadata:\nname: \"{{ .params.CLUSTER_NAME }}\"\npath: \"clusters/{{ .params.CLUSTER_NAME }}.yaml\"\nv1alpha1 notes","text":"The original version of the template. This version no longer works with Weave Gitops Enterprise 0.28.0 and above.
It uses spec.resourcetemplates as a list of resources to render.
Example:
spec:\nresourcetemplates:\n- apiVersion: cluster.x-k8s.io/v1alpha3\nkind: Cluster\nmetadata:\nname: \"{{ .params.CLUSTER_NAME }}\"\nWarning
This feature is in alpha and certain aspects will change
We're very excited for people to use this feature. However, please note that some changes will be made to the API and behavior, particularly to enhance security by implementing impersonation for more fine-grained control over how the generated resources are applied.
"},{"location":"gitopssets/#introduction","title":"Introduction","text":"GitOpsSets enable Platform Operators to have a single definition for an application for multiple environments and a fleet of clusters. A single definition can be used to generate the environment and cluster-specific configuration.
As an example, we can take an application that needs to be deployed to various environments (Dev, Test, Prod) built by a fleet of clusters. Each of those environments + clusters requires a specialized configuration powering the same Application. With GitOpsSets and the generators you just declare the template you want to use, the selector that will match the cluster of the inventory, and where to get the special configuration.
GitOpsSets will create out of the single resource all the objects and Flux primitives that are required to successfully deploy this application. An operation that required the editing of hundreds of files can now be done with a single command.
The initial generators that are coming with the preview release are:
The gitopssets-controller can be installed in two ways:
The standalone installation can be useful for leaf clusters that don't have Weave GitOps Enterprise installed.
"},{"location":"gitopssets/gitopssets-installation/#prerequisites","title":"Prerequisites","text":"Before installing the gitopssets-controller, ensure that you've installed Flux.
"},{"location":"gitopssets/gitopssets-installation/#installing-the-gitopssets-controller","title":"Installing the gitopssets-controller","text":"To install the gitopssets-controller using a Helm chart, use the following HelmRelease:
apiVersion: v1\nkind: Namespace\nmetadata:\nname: gitopssets-system\n---\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: HelmRepository\nmetadata:\nname: weaveworks-oci-charts\nnamespace: gitopssets-system\nspec:\ninterval: 1m\ntype: oci\nurl: oci://ghcr.io/weaveworks/charts\n---\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: gitopssets-controller\nnamespace: gitopssets-system\nspec:\ninterval: 10m\nchart:\nspec:\nchart: gitopssets-controller\nsourceRef:\nkind: HelmRepository\nname: weaveworks-oci-charts\nnamespace: gitopssets-system\nversion: 0.15.3\ninstall:\ncrds: CreateReplace\nupgrade:\ncrds: CreateReplace\nAfter adding the Namespace, HelmRepository and HelmRelease to a Git repository synced by Flux, commit the changes to complete the installation process.
"},{"location":"gitopssets/gitopssets-installation/#customising-the-generators","title":"Customising the Generators","text":"Not all generators are enabled by default, this is because not all CRDs are required by the generators.
You might want to enable or disable individual generators via the Helm Chart:
gitopssets-controller:\nenabled: true\ncontrollerManager:\nmanager:\nargs:\n- --health-probe-bind-address=:8081\n- --metrics-bind-address=127.0.0.1:8080\n- --leader-elect\n# enable the cluster generator which is not enabled by default\n- --enabled-generators=GitRepository,Cluster,PullRequests,List,APIClient,Matrix,Config\n2023-09-06
2023-09-05
2023-08-17
2023-08-17
2023-08-17
2023-08-10
2023-07-26
2023-07-14
2023-06-26
2023-06-21
2023-06-20
2023-05-24
2023-05-10
2023-04-28
2023-04-27
2023-04-13
2023-03-30
2023-03-20
Currently rendering templates operates in two phases:
Please read the security information below before using this.
"},{"location":"gitopssets/templating-from-generators/#general-behaviour","title":"General behaviour","text":"GitOpsSets can be suspended, by setting the spec.suspend flag to be true.
When this is the case, updates will not be applied, no resources created or deleted.
In addition, a manual reconciliation can be requested by annotating a GitOpsSet with the reconcile.fluxcd.io/requestedAt annotation.
The simplest generator is the List generator.
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: gitopsset-sample\nspec:\ngenerators:\n- list:\nelements:\n- env: dev\nteam: dev-team\n- env: production\nteam: ops-team\n- env: staging\nteam: ops-team\nThe elements in there are a set JSON of objects[^yaml], there are three in this example, and each of them has two keys, env and team.
Other generators provide different sets of keys and values.
The generators documentation below provides more information on what the other generators output.
"},{"location":"gitopssets/templating-from-generators/#rendering-templates","title":"Rendering templates","text":"Templates are Kubernetes resources in YAML format.
Each template is rendered for each element generated by the generators.
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: gitopsset-sample\nspec:\ngenerators:\n- list:\nelements:\n- env: dev\nteam: dev-team\n- env: production\nteam: ops-team\n- env: staging\nteam: ops-team\ntemplates:\n- content:\nkind: Kustomization\napiVersion: kustomize.toolkit.fluxcd.io/v1beta2\nmetadata:\nname: \"{{ .Element.env }}-demo\"\nlabels:\napp.kubernetes.io/name: go-demo\napp.kubernetes.io/instance: \"{{ .Element.env }}\"\ncom.example/team: \"{{ .Element.team }}\"\nspec:\ninterval: 5m\npath: \"./examples/kustomize/environments/{{ .Element.env }}\"\nprune: true\nsourceRef:\nkind: GitRepository\nname: go-demo-repo\nThe generated elements are provided to the template in the Element scope, so .Element.dev refers to the dev field from the List element.
The output from all generators is exposed in the Element scope, not just List generators.
In addition to the .Element field, a .ElementIndex is also available, this represents the zero-based index into the set of generated elements.
NOTE: It's not recommended that you use this to name resources where the ordering of the queries for generating the elements is not guaranteed to be ordered, otherwise you could generate churn in resources as we look for resources by name when updating them, so, .ElementIndex 1 may not be the same as .ElementIndex 1 was the previous time, and this could cause resources to be updated unnecessarily with undesirable effects.
The output from a generator is an array of JSON objects[^yaml], the keys of which can contain repeating elements, either further JSON objects, or scalar values.
It can be desirable to repeat a template for a repeated element in a generated value.
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: repeated-gitopsset-sample\nspec:\ngenerators:\n- list:\nelements:\n- env: dev\nteam: dev-team\nteams:\n- name: \"team1\"\n- name: \"team2\"\n- name: \"team3\"\n- env: staging\nteam: staging-team\nteams:\n- name: \"team4\"\n- name: \"team5\"\n- name: \"team6\"\ntemplates:\n- repeat: \"{ .teams }\"\ncontent:\nkind: ConfigMap\napiVersion: v1\nmetadata:\nname: \"{{ .Repeat.name }}-demo\"\ndata:\nname: \"{{ .Repeat.name }}-demo\"\nteam: \"{{ .Element.team }}\"\nThe template repeat field is a JSONPath expression that is applied to each element during the template rendering.
Templates that use repeat will have two separate scopes for the template params, .Element which is the top-level element generated by the generator, and the additional .Repeat scope, which is the repeating element.
In this case, six different ConfigMaps are generated, three for the \"dev-team\" and three for the \"staging-team\".
As with the .ElementIndex, for repeated elements both .ElementIndex and .RepeatIndex are available.
The default delimiters for the template engine are {{ and }}, which is the same as the Go template engine.
These can be changed by adding an annotation to the GitOpsSet:
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: gitopsset-sample\nannotations:\ntemplates.weave.works/delimiters: \"${{,}}\"\nChanging the delimiters can useful for:
In yaml {{ is invalid syntax and needs to be quoted. If you need to provide a un-quoted number value like replicas: 3 you should use the ${{,}} delimiters.
Unquoted values allow you to include objects in your templates too.
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: gitopsset-sample\nannotations:\ntemplates.weave.works/delimiters: \"${{,}}\"\nspec:\ngenerators:\n- list:\nelements:\n- env: dev\nresources:\nlimits:\ncpu: 100m\nmemory: 128Mi\n- env: staging\nresources:\nlimits:\ncpu: 100m\nmemory: 128Mi\ntemplates:\n- content:\nkind: Deployment\napiVersion: apps/v1\nmetadata:\nname: go-demo\nspec:\ntemplate:\nspec:\ncontainers:\n- name: go-demo\nimage: weaveworks/go-demo:0.2.0\nresources: ${{ .Element.resources | toJson }}\nWith the default {{,}} delimiters this would fail as the \"resources\" field would need to be quoted.
Again, if we quote them we would get a string value, not an object.
"},{"location":"gitopssets/templating-from-generators/#generators","title":"Generators","text":"We currently provide these generators: - list - pullRequests - gitRepository - ociRepository - matrix - apiClient - cluster - imagepolicy - config
"},{"location":"gitopssets/templating-from-generators/#list-generator","title":"List generator","text":"This is the simplest generator, which is a hard-coded array of JSON objects, described as YAML mappings.
"},{"location":"gitopssets/templating-from-generators/#gitrepository-generator","title":"GitRepository generator","text":"The GitRepository generator operates on Flux GitRepositories.
When a GitRepository is updated, this will trigger a regeneration of templates.
The generator operates in two different ways, you can parse files (YAML or JSON) into Elements, or you can scan directories for subdirectories.
"},{"location":"gitopssets/templating-from-generators/#generation-from-files","title":"Generation from files","text":"apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: repository-sample\nspec:\ngenerators:\n- gitRepository:\nrepositoryRef: go-demo-repo\nfiles:\n- path: examples/generation/dev.yaml\n- path: examples/generation/production.yaml\n- path: examples/generation/staging.yaml\ntemplates:\n- content:\nkind: Kustomization\napiVersion: kustomize.toolkit.fluxcd.io/v1beta2\nmetadata:\nname: \"{{ .Element.env }}-demo\"\nlabels:\napp.kubernetes.io/name: go-demo\napp.kubernetes.io/instance: \"{{ .Element.env }}\"\ncom.example/team: \"{{ .Element.team }}\"\nspec:\ninterval: 5m\npath: \"./examples/kustomize/environments/{{ .Element.env }}\"\nprune: true\nsourceRef:\nkind: GitRepository\nname: go-demo-repo\nIn this example, a Flux GitRepository called go-demo-repo in the same namespace as the GitOpsSet will be tracked, and Kustomization resources will be generated from the three files listed.
These files can be JSON or YAML.
In this example we expect to find the following structure in the files:
env: dev\nteam: developers\nChanges pushed to the GitRepository will result in rereconciliation of the templates into the cluster.
For security reasons, you need to explicitly list out the files that the generator should parse.
"},{"location":"gitopssets/templating-from-generators/#generation-from-directories","title":"Generation from directories","text":"apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nlabels:\napp.kubernetes.io/name: gitopsset\napp.kubernetes.io/instance: gitopsset-sample\napp.kubernetes.io/part-of: gitopssets-controller\napp.kubernetes.io/managed-by: kustomize\napp.kubernetes.io/created-by: gitopssets-controller\nname: repository-sample\nspec:\ngenerators:\n- gitRepository:\nrepositoryRef: go-demo-repo\ndirectories:\n- path: examples/kustomize/environments/*\ntemplates:\n- content:\nkind: Kustomization\napiVersion: kustomize.toolkit.fluxcd.io/v1beta2\nmetadata:\nname: \"{{ .Element.Base }}-demo\"\nlabels:\napp.kubernetes.io/name: go-demo\napp.kubernetes.io/instance: \"{{ .Element.Base }}\"\ncom.example/team: \"{{ .Element.Base }}\"\nspec:\ninterval: 5m\npath: \"{{ .Element.Directory }}\"\nprune: true\nsourceRef:\nkind: GitRepository\nname: go-demo-repo\nIn this example, a Flux GitRepository called go-demo-repo in the same namespace as the GitOpsSet will be tracked, and Kustomization resources are generated from paths within the examples/kustomize/environments/* directory within the repository.
Each generated element has two keys, .Element.Directory which will be a repo-relative path and .Element.Base which contains the last element of the path, for example, for a directory ./examples/kustomize/environments/production this will be production.
It is also possible to exclude paths from the generated list, for example, if you do not want to generate for a directory you can exclude it with:
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: repository-sample\nspec:\ngenerators:\n- gitRepository:\nrepositoryRef: go-demo-repo\ndirectories:\n- path: examples/kustomize/environments/*\n- path: examples/kustomize/environments/production\nexclude: true\ntemplates:\n- content:\nIn this case, all directories that are subdirectories of examples/kustomize/environments will be generated, but not examples/kustomize/environments/production.
Note: The directory tree detection is restricted to the same directory as the path, no recursion is done.
In fact the path is treated as a Glob.
"},{"location":"gitopssets/templating-from-generators/#ocirepository-generator","title":"OCIRepository generator","text":"The OCIRepository generator operates on Flux OCIRepositories.
When an OCIRepository is updated, this will trigger a regeneration of templates.
The OCIRepository generator operates in exactly the same way as the GitRepository generator, except it operates on OCIRepositories.
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: oci-repository-sample\nspec:\ngenerators:\n- ociRepository:\nrepositoryRef: go-demo-oci-repo\nfiles:\n- path: examples/generation/dev.yaml\n- path: examples/generation/production.yaml\n- path: examples/generation/staging.yaml\ntemplates:\n- content:\nkind: Kustomization\napiVersion: kustomize.toolkit.fluxcd.io/v1beta2\nmetadata:\nname: \"{{ .Element.env }}-demo\"\nlabels:\napp.kubernetes.io/name: go-demo\napp.kubernetes.io/instance: \"{{ .Element.env }}\"\ncom.example/team: \"{{ .Element.team }}\"\nspec:\ninterval: 5m\npath: \"./examples/kustomize/environments/{{ .Element.env }}\"\nprune: true\nsourceRef:\nkind: GitRepository\nname: go-demo-repo\nThis will require to make authenticated requests to your Git hosting provider e.g. GitHub, GitLab, Bitbucket etc.
It does only require read-only access, but all API tokens should be guarded as carefully as possible, what is a \"read-only\" token today, might become a token with higher-privilege in the future.
There have been many security compromises using API access tokens, do not let this happen to you!
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: pull-requests-sample\nspec:\ngenerators:\n- pullRequests:\ninterval: 5m\ndriver: github\nrepo: bigkevmcd/go-demo\nsecretRef:\nname: github-secret\ntemplates:\n- content:\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: GitRepository\nmetadata:\nname: \"pr-{{ .Element.Number }}-gitrepository\"\nnamespace: default\nspec:\ninterval: 5m0s\nurl: \"{{ .Element.CloneURL }}\"\nref:\nbranch: \"{{ .Element.Branch }}\"\n- content:\napiVersion: kustomize.toolkit.fluxcd.io/v1beta2\nkind: Kustomization\nmetadata:\nname: \"pr-{{ .Element.Number }}-demo\"\nnamespace: default\nspec:\ninterval: 5m\npath: \"./examples/kustomize/environments/dev\"\nprune: true\ntargetNamespace: \"{{ .Element.Branch }}-ns\"\nsourceRef:\nkind: GitRepository\nname: \"pr-{{ .Element.Number }}-gitrepository\"\nThis example will poll \"github.com/bigkevmcd/go-demo\" for open pull requests and trigger the deployment of these by creating a Flux GitRepository and a Kustomization to deploy.
As the generator only queries open pull requests, when a PR is closed, the generated resources will be removed.
For non-public installations, you can configure the serverURL field and point it to your own installation.
The driver field can be github or gitlab or bitbucketserver, other options can be supported from go-scm.
The forks flag field can be used to indicate whether to include forks in the target pull requests or not. If set to true any pull request from a fork repository will be included, otherwise if false or not indicated the pull requests from fork repositories are discarded.
Additionally labels can be provided for querying pull requests with matching labels e.g.
- pullRequests:\ninterval: 5m\ndriver: github\nrepo: bigkevmcd/go-demo\nsecretRef:\nname: github-secret\nforks: false\nlabels:\n- deploy\nThe fields emitted by the pull-request are as follows:
Create a read-only token that can list Pull Requests, and store it in a secret:
$ kubectl create secret generic github-secret \\\n--from-literal password=<insert access token here>\nThe matrix generator doesn't generate resources by itself. It combines the results of generation from other generators e.g.:
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: matrix-sample\nspec:\ngenerators:\n- matrix:\ngenerators:\n- gitRepository:\nrepositoryRef: go-demo-repo\nfiles:\n- path: examples/generation/dev.yaml\n- path: examples/generation/production.yaml\n- path: examples/generation/staging.yaml\n- list:\nelements:\n- cluster: dev-cluster\nversion: 1.0.0\nGiven the files mentioned all have the following structure:
env: dev\nteam: developers\nThis will result in three sets of generated parameters, which are a combination of the maps in the files in the gitRepository, and the elements in the list generator, this can result in a combinatorial explosion of resources being created in your cluster.
- env: dev\nteam: developers\ncluster: dev-cluster\nversion: 1.0.0\n- env: staging\nteam: staging-team\ncluster: dev-cluster\nversion: 1.0.0\n- env: production\nteam: production-team\ncluster: dev-cluster\nversion: 1.0.0\nThese can be referenced in the templates, note that all keys in the merged generators from the Matrix are contained in the Element scope.
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: matrix-sample\nspec:\ngenerators:\n- matrix:\ngenerators:\n- gitRepository:\nrepositoryRef: go-demo-repo\nfiles:\n- path: examples/generation/dev.yaml\n- path: examples/generation/production.yaml\n- path: examples/generation/staging.yaml\n- list:\nelements:\n- cluster: dev-cluster\nversion: 1.0.0\ntemplates:\n- content:\nkind: Kustomization\napiVersion: kustomize.toolkit.fluxcd.io/v1beta2\nmetadata:\nname: \"{{ .Element.env }}-demo\"\nlabels:\napp.kubernetes.io/name: go-demo\napp.kubernetes.io/instance: \"{{ .Element.env }}\"\ncom.example/team: \"{{ .Element.team }}\"\ncom.example/cluster: \"{{ .Element.cluster }}\"\ncom.example/version: \"{{ .Element.version }}\"\nspec:\ninterval: 5m\npath: \"./examples/kustomize/environments/{{ .Element.env }}\"\nprune: true\nsourceRef:\nkind: GitRepository\nname: go-demo-repo\nIf you want to use two generators in a Matrix that output the same fields, they will collide, for example, the ImagePolicy generator outputs a latestImage field, if you have two, they will collide.
You can provide a name for the generator in the Matrix:
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: matrix-sample\nspec:\ngenerators:\n- matrix:\ngenerators:\n- name: gen1\ngitRepository:\nrepositoryRef: go-demo-repo\nfiles:\n- path: examples/generation/dev.yaml\n- path: examples/generation/production.yaml\n- path: examples/generation/staging.yaml\n- name: gen2\nlist:\nelements:\n- cluster: dev-cluster\nversion: 1.0.0\ntemplates:\n- content:\nkind: Kustomization\napiVersion: kustomize.toolkit.fluxcd.io/v1beta2\nmetadata:\nname: \"{{ .Element.gen1.env }}-demo\"\nlabels:\napp.kubernetes.io/name: go-demo\napp.kubernetes.io/instance: \"{{ .Element.gen1.env }}\"\ncom.example/team: \"{{ .Element.gen1.team }}\"\ncom.example/cluster: \"{{ .Element.gen2.cluster }}\"\ncom.example/version: \"{{ .Element.gen2.version }}\"\nspec:\ninterval: 5m\npath: \"./examples/kustomize/environments/{{ .Element.gen1.env }}\"\nprune: true\nsourceRef:\nkind: GitRepository\nname: go-demo-repo\nThe example above will yield:
- gen1:\nenv: dev\nteam: developers\ngen2:\ncluster: dev-cluster\nersion: 1.0.0\n- gen1:\nenv: staging\nteam: staging-team\ngen2:\ncluster: dev-cluster\nversion: 1.0.0\n- gen1:\nenv: production\nteam: production-team\ngen2:\ncluster: dev-cluster\nversion: 1.0.0\nA matrix generator will normally generate a cartesian result, but you can also generate a single result.
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: single-element-matrix-sample\nspec:\ngenerators:\n- matrix:\nsingleElement: true\ngenerators:\n- name: staging\ncluster:\nselector:\nmatchLabels:\nenv: staging\n- name: production\ncluster:\nselector:\nmatchLabels:\nenv: production\nThis would query for clusters matching the respective labels.
The resulting output would look like this (in YAML):
- production:\n- ClusterAnnotations: {}\nClusterLabels:\nenv: production\nClusterName: production-cluster1\nClusterNamespace: clusters\n- ClusterAnnotations: {}\nClusterLabels:\nenv: production\nClusterName: production-cluster2\nClusterNamespace: clusters\nstaging:\n- ClusterAnnotations: {}\nClusterLabels:\nenv: staging\nClusterName: staging-cluster1\nClusterNamespace: clusters\n- ClusterAnnotations: {}\nClusterLabels:\nenv: staging\nClusterName: staging-cluster2\nClusterNamespace: clusters\nCompare this with the alternative without the singleElement flag:
- production:\nClusterAnnotations: {}\nClusterLabels:\nenv: production\nClusterName: production-cluster1\nClusterNamespace: clusters\nstaging:\nClusterAnnotations: {}\nClusterLabels:\nenv: staging\nClusterName: staging-cluster1\nClusterNamespace: clusters\n- production:\nClusterAnnotations: {}\nClusterLabels:\nenv: production\nClusterName: production-cluster2\nClusterNamespace: clusters\nstaging:\nClusterAnnotations: {}\nClusterLabels:\nenv: staging\nClusterName: staging-cluster1\nClusterNamespace: clusters\n- production:\nClusterAnnotations: {}\nClusterLabels:\nenv: production\nClusterName: production-cluster1\nClusterNamespace: clusters\nstaging:\nClusterAnnotations: {}\nClusterLabels:\nenv: staging\nClusterName: staging-cluster2\nClusterNamespace: clusters\n- production:\nClusterAnnotations: {}\nClusterLabels:\nenv: production\nClusterName: production-cluster2\nClusterNamespace: clusters\nstaging:\nClusterAnnotations: # omitted\nClusterLabels:\nenv: staging\nClusterName: staging-cluster2\nClusterNamespace: clusters\nIn the singleElement case, there is only one generated element, only one template will be rendered for each content item.
If the Matrix generators are unnamed, they will be grouped under a top-level .Matrix name.
This generator is configured to poll an HTTP endpoint and parse the result as the generated values.
This will poll an endpoint on the interval, instead of using the simpler to use PullRequest generator, you can access GitHub's API with the APIClient generator.
The PullRequest generator is simpler to use, and works across multiple different git-providers.
The GitHub documentation for the API endpoint shows:
curl \\\n-H \"Accept: application/vnd.github+json\" \\\n-H \"Authorization: Bearer <YOUR-TOKEN>\"\\\n-H \"X-GitHub-Api-Version: 2022-11-28\" \\\nhttps://api.github.com/repos/OWNER/REPO/pulls\nThis can be translated into...
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nlabels:\napp.kubernetes.io/name: gitopsset\napp.kubernetes.io/instance: gitopsset-sample\napp.kubernetes.io/part-of: gitopssets-controller\napp.kubernetes.io/managed-by: kustomize\napp.kubernetes.io/created-by: gitopssets-controller\nname: api-client-sample\nspec:\ngenerators:\n- apiClient:\ninterval: 5m\nendpoint: https://api.github.com/repos/bigkevmcd/go-demo/pulls\nheadersRef:\nname: github-secret\nkind: Secret\ntemplates:\n- content:\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: GitRepository\nmetadata:\nname: \"pr-{{ .Element.id | toJson}}-gitrepository\"\nnamespace: default\nspec:\ninterval: 5m0s\nurl: \"{{ .Element.head.repo.clone_url }}\"\nref:\nbranch: \"{{ .Element.head.ref }}\"\n- content:\napiVersion: kustomize.toolkit.fluxcd.io/v1beta2\nkind: Kustomization\nmetadata:\nname: \"pr-{{ .Element.id | toJson }}-demo\"\nnamespace: default\nspec:\ninterval: 5m\npath: \"./examples/kustomize/environments/dev\"\nprune: true\ntargetNamespace: \"{{ .Element.head.ref }}-ns\"\nsourceRef:\nkind: GitRepository\nname: \"pr-{{ .Element.id | toJson }}-gitrepository\"\nAs with the Pull Request generator, this also requires a secret token to be able to access the API
We need to pass this as an HTTP header.
apiVersion: v1\nkind: Secret\nmetadata:\nname: github-secret\nnamespace: default\ntype: Opaque\nstringData:\nAccept: application/vnd.github+json\nAuthorization: Bearer ghp_<redacted>\nX-GitHub-Api-Version: \"2022-11-28\"\nThe keys in the secret match the command-line example using curl.
Unlike the Pull Request generator, you need to figure out the paths to the elements yourself.
"},{"location":"gitopssets/templating-from-generators/#apiclient-jsonpath","title":"APIClient JSONPath","text":"Not all APIs return an array of JSON objects, sometimes it's nested within a result type structure e.g.
{\n\"things\": [\n{\n\"env\": \"dev\",\n\"team\": \"dev-team\"\n},\n{\n\"env\": \"production\",\n\"team\": \"opts-team\"\n},\n{\n\"env\": \"staging\",\n\"team\": \"opts-team\"\n}\n]\n}\nYou can use JSONPath to extract the fields from this data...
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nlabels:\napp.kubernetes.io/name: gitopsset\napp.kubernetes.io/instance: gitopsset-sample\napp.kubernetes.io/part-of: gitopssets-controller\napp.kubernetes.io/managed-by: kustomize\napp.kubernetes.io/created-by: gitopssets-controller\nname: api-client-sample\nspec:\ngenerators:\n- apiClient:\ninterval: 5m\nendpoint: https://api.example.com/demo\njsonPath: \"{ $.things }\"\nThis will generate three maps for templates, with just the env and team keys.
"},{"location":"gitopssets/templating-from-generators/#apiclient-post-body","title":"APIClient POST body","text":"Another piece of functionality in the APIClient generator is the ability to POST JSON to the API.
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nlabels:\napp.kubernetes.io/name: gitopsset\napp.kubernetes.io/instance: gitopsset-sample\napp.kubernetes.io/part-of: gitopssets-controller\napp.kubernetes.io/managed-by: kustomize\napp.kubernetes.io/created-by: gitopssets-controller\nname: api-client-sample\nspec:\ngenerators:\n- apiClient:\ninterval: 5m\nendpoint: https://api.example.com/demo\nbody:\nname: \"testing\"\nvalue: \"testing2\"\nThis will send a request body as JSON (Content-Type \"application/json\") to the server and interpret the result.
The JSON body sent will look like this:
{ \"name\": \"testing\", \"value\": \"testing2\" }\nInstead of using the JSONPath to extract from a complex structure, you can configure the result to be a single element.
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nlabels:\napp.kubernetes.io/name: gitopsset\napp.kubernetes.io/instance: gitopsset-sample\napp.kubernetes.io/part-of: gitopssets-controller\napp.kubernetes.io/created-by: gitopssets-controller\nname: api-client-sample\nspec:\ngenerators:\n- apiClient:\nsingleElement: true\ninterval: 5m\nendpoint: https://api.example.com/demo\nWhatever result is parsed from the API endpoint will be returned as a map in a single element.
For generation, you might need to use the repeat mechanism to generate repeating results.
If the API endpoint you are accessing requires a custom CA you can provide this via the secret field.
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nlabels:\napp.kubernetes.io/name: gitopsset\napp.kubernetes.io/instance: gitopsset-sample\napp.kubernetes.io/part-of: gitopssets-controller\napp.kubernetes.io/created-by: gitopssets-controller\nname: api-client-sample\nspec:\ngenerators:\n- apiClient:\nsingleElement: true\ninterval: 5m\nendpoint: https://api.example.com/demo\nsecretRef:\nname: https-ca-credentials\nThis secret should look like this:
---\napiVersion: v1\nkind: Secret\nmetadata:\nname: https-ca-credentials\ntype: Opaque\ndata:\ncaFile: <BASE64>\nThe request will be made with the custom CA.
"},{"location":"gitopssets/templating-from-generators/#cluster-generator","title":"Cluster generator","text":"The cluster generator generates from in-cluster GitOpsCluster resources.
For example, this GitOpsSet will generate a Kustomization resource for each cluster matching the Label selector.
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: cluster-sample\nspec:\ngenerators:\n- cluster:\nselector:\nmatchLabels:\nenv: dev\nteam: dev-team\ntemplates:\n- content:\nkind: Kustomization\napiVersion: kustomize.toolkit.fluxcd.io/v1beta2\nmetadata:\nname: \"{{ .Element.ClusterName }}-demo\"\nlabels:\napp.kubernetes.io/name: go-demo\napp.kubernetes.io/instance: \"{{ .Element.ClusterName }}\"\ncom.example/team: \"{{ .Element.ClusterLabels.team }}\"\nspec:\ninterval: 5m\npath: \"./examples/kustomize/environments/{{ .Element.ClusterLabels.env }}\"\nprune: true\nsourceRef:\nkind: GitRepository\nname: go-demo-repo\nThe following fields are generated for each GitOpsCluster.
If the selector is not provided, all clusters from all namespaces will be returned:
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: cluster-sample\nspec:\ngenerators:\n- cluster: {}\nOtherwise if the selector is empty, no clusters will be generated:
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: cluster-sample\nspec:\ngenerators:\n- cluster:\nselector: {}\nThe ImagePolicy generator works with the Flux Image Automation.
When an ImagePolicy is updated, this will trigger a regeneration of templates.
The generated elements have the following fields:
This can be used simply, to create a deployment with an image...or, combined with a Matrix generator, to manage multiple workloads with the same image.
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: imagepolicy-example\nnamespace: default\nspec:\ngenerators:\n- imagePolicy:\npolicyRef: podinfo\ntemplates:\n- content:\nkind: ConfigMap\napiVersion: v1\nmetadata:\nname: \"demo-configmap\"\ndata:\nimage: \"{{ .Element.latestImage }}\"\nIn this example, a ConfigMap is generated containing the latest image whenever an ImagePolicy called podinfo is updated.
Combined in a Matrix, like this, it will generate two ConfigMaps with the values.
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: imagepolicy-matrix-example\nnamespace: default\nspec:\ngenerators:\n- matrix:\ngenerators:\n- imagePolicy:\npolicyRef: podinfo\n- list:\nelements:\n- cluster: dev-cluster\nversion: 1.0.0\n- cluster: prod-cluster\nversion: 1.0.0\ntemplates:\n- content:\nkind: ConfigMap\napiVersion: v1\nmetadata:\nname: \"demo-configmap-{{ .Element.cluster }}\"\ndata:\nimage: \"{{ .Element.latestImage }}\"\ncluster: \"{{ .Element.cluster }}\"\nversion: \"{{ .Element.version }}\"\nThe resulting ConfigMaps look like this:
$ kubectl get configmaps\nNAME DATA AGE\ndemo-configmap-dev-cluster 3 3m19s\ndemo-configmap-prod-cluster 3 3m19s\nWith the templated fields like this:
apiVersion: v1\nkind: ConfigMap\nmetadata:\nname: demo-configmap-dev-cluster\nnamespace: default\ndata:\ncluster: dev-cluster\nimage: stefanprodan/podinfo:5.1.4\nversion: 1.0.0\napiVersion: v1\nkind: ConfigMap\nmetadata:\nname: demo-configmap-prod-cluster\nnamespace: default\ndata:\ncluster: prod-cluster\nimage: stefanprodan/podinfo:5.1.4\nversion: 1.0.0\nThe Config generator with Kubernetes ConfigMaps and Secrets.
When an ConfigMap or Secret is updated, this will trigger a regeneration of templates.
This can be used simply, to create a resource with an config variable...or, combined with a Matrix generator, to manage multiple workloads with the same values.
With the existing ConfigMap
apiVersion: v1\nkind: ConfigMap\nmetadata:\nname: test-cm\ndata:\nname: test-config\ndemo: test-value\napiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: config-sample\nspec:\ngenerators:\n- config:\nkind: ConfigMap\nname: test-cm\ntemplates:\n- content:\nkind: ConfigMap\napiVersion: v1\nmetadata:\nname: \"{{ .Element.name }}-demo\"\nlabels:\napp.kubernetes.io/name: go-demo\napp.kubernetes.io/instance: \"{{ .Element.name }}\"\ndata:\ngeneratedValue: \"{{ .Element.demo }}\"\nConfigMap is generated containing the value of the \"demo\" field from the existing ConfigMap test-cm. As with the other generators, the Config generator can be combined with other generators:
This will generate two ConfigMaps with the values.
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: imagepolicy-matrix-example\nnamespace: default\nspec:\ngenerators:\n- matrix:\ngenerators:\n- config:\nkind: ConfigMap\nname: test-cm\n- list:\nelements:\n- cluster: dev-cluster\nversion: 1.0.0\n- cluster: prod-cluster\nversion: 1.0.0\ntemplates:\n- content:\nkind: ConfigMap\napiVersion: v1\nmetadata:\nname: \"demo-configmap-{{ .Element.cluster }}\"\ndata:\ngeneratedValue: \"{{ .Element.demo }}\"\ncluster: \"{{ .Element.cluster }}\"\nversion: \"{{ .Element.version }}\"\nThe resulting ConfigMaps look like this:
$ kubectl get configmaps\nNAME DATA AGE\ndemo-configmap-dev-cluster 3 3m19s\ndemo-configmap-prod-cluster 3 3m19s\nWith the templated fields like this:
apiVersion: v1\nkind: ConfigMap\nmetadata:\nname: demo-configmap-dev-cluster\nnamespace: default\ndata:\ncluster: dev-cluster\ngeneratedValue: test-value\nversion: 1.0.0\napiVersion: v1\nkind: ConfigMap\nmetadata:\nname: demo-configmap-prod-cluster\nnamespace: default\ndata:\ncluster: prod-cluster\ngeneratedValue: test-value\nversion: 1.0.0\nCurrently, the Sprig functions are available in the templating, with some functions removed[^sprig] for security reasons.
In addition, we also provide two additional functions:
The examples below assume an element that looks like this:
{\n\"team\": \"engineering dev\"\n}\nAnd a template that looks like this:
kind: Service\nmetadata:\nname: {{ sanitize .Element.team }}-demo\nThis would output:
kind: Service\nmetadata:\nname: engineeringdev-demo\nFor template that looks like this:
kind: Service\nmetadata:\nname: {{ getordefault .Element \"name\" \"defaulted\" }}-demo\nThis would output:
kind: Service\nmetadata:\nname: defaulted-demo\nIf the key to get does exist in the .Element it will be inserted, the \"default\" is only inserted if it doesn't exist.
Warning
Generating resources and applying them directly into your cluster can be dangerous to the health of your cluster.
This is especially true for the GitRepository generator, where it may not be obvious to the author of the files, or the author of the template the consequences of the template rendering.
The default ServiceAccount that is used by the gitopssets-controller is extremely limited, and can not create resources, you will need to explicitly grant permissions to create any of the resources you declare in the template, missing permissions will appear in the controller logs.
It is not recommended that you create a role with blanket permissions, under the right circumstances, someone could accidentally or maliciously overwrite the cluster control-plane, which could be very dangerous.
"},{"location":"gitopssets/templating-from-generators/#limiting-via-service-accounts","title":"Limiting via service-accounts","text":"You can configure the service-account that is used to create resources.
apiVersion: templates.weave.works/v1alpha1\nkind: GitOpsSet\nmetadata:\nname: matrix-sample\nspec:\n# the controller will impersonate this service account\nserviceAccountName: test-sa\ngenerators:\n- list:\nelements:\n- env: dev\nteam: dev-team\n- env: production\nteam: ops-team\n- env: staging\nteam: ops-team\ntemplates:\n- content:\nkind: Kustomization\napiVersion: kustomize.toolkit.fluxcd.io/v1beta2\nmetadata:\nname: \"{{ .Element.env }}-demo\"\nlabels:\napp.kubernetes.io/name: go-demo\napp.kubernetes.io/instance: \"{{ .Element.env }}\"\ncom.example/team: \"{{ .Element.team }}\"\nspec:\ninterval: 5m\npath: \"./examples/kustomize/environments/{{ .Element.env }}\"\nprune: true\nsourceRef:\nkind: GitRepository\nname: go-demo-repo\nThe enabled generators can be configured via the --enabled-generators flag, which takes a comma separated list of generators to enable.
The default is to enable all generators.
For example to enable only the List and GitRepository generators:
--enabled-generators=List,GitRepository\nWhen a GitOpsSet that uses disabled generators is created, the disabled generators will be silently ignored.
"},{"location":"gitopssets/templating-from-generators/#kubernetes-process-limits","title":"Kubernetes Process Limits","text":"GitOpsSets can be memory-hungry, for example, the Matrix generator will generate a cartesian result with multiple copies of data.
The OCI and GitRepository generators will extract tarballs, the API Generator queries upstream APIs and parses the JSON, and the Config generators will load Secret and ConfigMap resources, all these can lead to using significant amounts of memory.
Extracting tarballs can also prove to be CPU intensive, especially where there are lots of files, and you have a very frequent regeneration period.
To this end, you will need to monitor the controller metrics, and maybe increase the limits available to the controller.
For example, to increase the amount of memory available to the controller:
resources:\nlimits:\ncpu: 1000m\nmemory: 2Gi\nrequests:\ncpu: 100m\nmemory: 64Mi\nEvents are enabled which will trigger Kubernetes events when successful reconciliation occurs with a Normal event or when reconciliation fails with an Error event. Fluxcd's Events package is used including the EventRecorder to record these events.
To configure receiving the recorded events on a specific host, this can be provided via the --events-addr flag in RUN_ARGS when starting the controller. This can be any HTTP endpoint.
See fluxcd event for the struct of the event created.
[^yaml]: These are written as YAML mappings [^sprig]: The following functions are removed \"env\", \"expandenv\", \"getHostByName\", \"genPrivateKey\", \"derivePassword\", \"sha256sum\", \"base\", \"dir\", \"ext\", \"clean\", \"isAbs\", \"osBase\", \"osDir\", \"osExt\", \"osClean\", \"osIsAbs\"
"},{"location":"guides/anonymous-access/","title":"Anonymous Access","text":"Important
Alone, this is an insecure method of securing your dashboard.
It is designed to be used with other external authentication systems like auth proxies.
"},{"location":"guides/anonymous-access/#configuring-anonymous-access","title":"Configuring Anonymous access","text":"Set the following values in the Helm Chart:
#\nadditionalArgs:\n- --insecure-no-authentication-user=gitops-test-user\n#\nThe value of the --insecure-no-authentication-user flag is the kubernetes User to be impersonated to make requests into the cluster.
When this flag is set all other authentication methods (e.g. those specified via --auth-methods) are disabled.
No login screen will be displayed when accessing the dashboard.
"},{"location":"guides/anonymous-access/#example-clusterrole","title":"Example ClusterRole","text":"You can bind the user provided to a ClusterRole with a ClusterRoleBinding.
---\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRole\nmetadata:\nname: minimum-weavegitops-role\nrules:\n- apiGroups: [\"\"]\nresources: [\"secrets\",\"pods\",\"events\"]\nverbs: [\"get\",\"list\"]\n- apiGroups: [\"apps\"]\nresources: [\"deployments\", \"replicasets\"]\nverbs: [\"get\",\"list\"]\n- apiGroups: [\"kustomize.toolkit.fluxcd.io\"]\nresources: [\"kustomizations\"]\nverbs: [\"get\",\"list\"]\n- apiGroups: [\"helm.toolkit.fluxcd.io\"]\nresources: [\"helmreleases\"]\nverbs: [\"get\",\"list\"]\n- apiGroups: [\"source.toolkit.fluxcd.io\"]\nresources: [\"*\"]\nverbs: [\"get\",\"list\"]\n- apiGroups: [\"\"]\nresources: [\"events\"]\nverbs: [\"get\",\"list\",\"watch\"]\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRoleBinding\nmetadata:\nname: gitops-test-user-binding\nroleRef:\napiGroup: rbac.authorization.k8s.io\nkind: ClusterRole\nname: minimum-weavegitops-role\nsubjects:\n- kind: User\nname: gitops-test-user\nThis would allow access to any resource.
"},{"location":"guides/displaying-custom-metadata/","title":"Displaying Custom Metadata","text":"Weave GitOps lets you add annotations with custom metadata to your Flux automations and sources, and they will be displayed in the main UI.
For example, you might use this to add links to dashboards, issue systems, or documentation and comments that you wish to be directly visible in the GitOps UI.
We will use the podinfo application that we installed in the getting started guide as an example. Open up the podinfo kustomization and add annotations to it so it looks like this:
---\napiVersion: kustomize.toolkit.fluxcd.io/v1beta2\nkind: Kustomization\nmetadata:\nname: podinfo\nnamespace: flux-system\n// highlight-start\nannotations:\nmetadata.weave.works/description: |\nPodinfo is a tiny web application made with Go that showcases best practices of running microservices in Kubernetes.\nPodinfo is used by CNCF projects like Flux and Flagger for end-to-end testing and workshops.\nmetadata.weave.works/grafana-dashboard: https://grafana.my-org.example.com/d/podinfo-dashboard\n// highlight-end\nspec:\ninterval: 5m0s\npath: ./kustomize\nprune: true\nsourceRef:\nkind: GitRepository\nname: podinfo\ntargetNamespace: flux-system\nClose the file and commit and push your changes.
Back in your GitOps dashboard, navigate to the 'Applications' tab and select the podinfo kustomization. At the bottom of the 'Details' section you will see the new 'Metadata' entries:
Restrictions
We are very excited for the release of the Flux v2.0 GA!
This guide aims to answer some common questions before starting the upgrade, and provides step-by-step instructions.
"},{"location":"guides/fluxga-upgrade/#before-starting-the-upgrade","title":"Before Starting the Upgrade","text":"Useful terms used in this guide:
Here you can find the most common questions around upgrading.
"},{"location":"guides/fluxga-upgrade/#why-upgrade-to-flux-ga","title":"Why Upgrade to Flux GA","text":"Although Flux Beta APIs have been stable and used in production for quite some time, Flux GA is the main supported API version for new features and development. Features like horizontal scaling are only available in Flux GA. Also, beta APIs will be removed after six months.
"},{"location":"guides/fluxga-upgrade/#can-i-use-weave-gitops-with-flux-ga","title":"Can I Use Weave GitOps with Flux GA?","text":"Yes. This has been possible since Weave Gitops v0.22.0. Use the latest available release for the best experience.
"},{"location":"guides/fluxga-upgrade/#can-i-use-weave-gitops-enterprise-with-flux-ga","title":"Can I Use Weave GitOps Enterprise with Flux GA?","text":"Yes. This has been possible since Weave GitOps Enterprise v0.22.0. Use the latest available release for the best experience.
The following limitations are knowns by version:
"},{"location":"guides/fluxga-upgrade/#v0230-onwards","title":"v0.23.0 onwards","text":"No limitations
"},{"location":"guides/fluxga-upgrade/#v0220","title":"v0.22.0","text":"If you are using GitOpsSets, upgrade that component to v0.10.0 for Flux GA compatibility. Update the Weave GitOps Enterprise HelmRelease values to use the new version.
gitopssets-controller:\ncontrollerManager:\nmanager:\nimage:\ntag: v0.10.0\nAs of Weave GitOps v0.29, only Flux v2.0 GA is supported. Please follow the Upgrade section to help you with the process.
Earlier versions of Weave GitOps work with both Flux v2 GA and Flux v2 0.x (the pre-GA ones), but it is encouraged that you upgrade to the latest version for the best experience.
"},{"location":"guides/fluxga-upgrade/#upgrade","title":"Upgrade","text":"Hosted flux?
If you are using a hosted Flux version, please check with your provider if they support Flux GA before upgrading following this guide. Known hosted Flux providers:
As of writing they do not yet support the new version, so please wait before upgrading to Flux GA.
Below, we'll take you through the multiple steps required to migrate to your system to Flux GA. After each step the cluster will be in a working state, so you can take your time to complete the migration.
Follow the upgrade instructions from the Flux v2.0.0 release notes.
At minimum, you'll need to rerun the flux bootstrap command on your leaf clusters and management clusters.
You'll also need to bump API versions in your manifests to v1 as described in the Flux upgrade instructions:
Bumping the APIs version in manifests can be done gradually. It is advised to not delay this procedure as the beta versions will be removed after 6 months.
At this stage all clusters are running Flux GA.
"},{"location":"guides/fluxga-upgrade/#2-upgrade-to-flux-ga-in-clusterbootstrapconfigs","title":"2. Upgrade to Flux GA in ClusterBootstrapConfigs","text":"First, we ensure any new clusters are bootstrapped with Flux GA. Then we'll upgrade the existing clusters.
ClusterBootstrapConfig will most often contain an invocation of flux bootstrap. Make sure the image is using v2.
diff --git a/tools/dev-resources/user-guide/cluster-bootstrap-config.yaml b/tools/dev-resources/user-guide/cluster-bootstrap-config.yaml\nindex bd41ec036..1b21df860 100644\n--- a/tools/dev-resources/user-guide/cluster-bootstrap-config.yaml\n+++ b/tools/dev-resources/user-guide/cluster-bootstrap-config.yaml\n@@ -1,34 +1,34 @@\napiVersion: capi.weave.works/v1alpha1\nkind: ClusterBootstrapConfig\nmetadata:\nname: capi-gitops\nnamespace: default\nspec:\nclusterSelector:\n matchLabels:\n weave.works/capi: bootstrap\njobTemplate:\n generateName: \"run-gitops-{{ .ObjectMeta.Name }}\"\n spec:\n containers:\n- - image: ghcr.io/fluxcd/flux-cli:v0.34.0\n+ - image: ghcr.io/fluxcd/flux-cli:v2.0.0\n name: flux-bootstrap\n ...\nAt this stage, your new bootstrapped clusters will run Flux GA.
"},{"location":"guides/fluxga-upgrade/#3-upgrade-to-latest-wge","title":"3. Upgrade to latest WGE","text":"Use your regular WGE upgrade procedure to bring it to the latest version
At this stage you have Weave GitOps running Flux GA.
"},{"location":"guides/fluxga-upgrade/#4-upgrade-gitopstemplates-gitopssets-and-clusterbootstrapconfigs","title":"4. Upgrade GitOpsTemplates, GitOpsSets, and ClusterBootstrapConfigs","text":"Bumping the APIs version in manifests can be done gradually. We advise against delaying this procedure as the Beta versions will be removed after six months.
"},{"location":"guides/fluxga-upgrade/#gitopstemplate-and-capitemplate","title":"GitOpsTemplate and CAPITemplate","text":"Update GitRepository and Kustomization CRs in the spec.resourcetemplates to v1 as described in the flux upgrade instructions.
GitOpsSets","text":"Update GitRepository and Kustomization CRs in the spec.template of your GitOpsSet resources to v1 as described in the Flux upgrade instructions.
If you haven't done it yet, plan to update your Kustomization , GitRepository and Receiver resources to v1, you can also upgrade to the future release of Flux that will drop support for < v1 APIs.
If you find any issues, please let us know via support.
"},{"location":"open-source/aws-marketplace/","title":"AWS Marketplace","text":""},{"location":"open-source/aws-marketplace/#aws-marketplace","title":"AWS Marketplace","text":"Weave GitOps is also available via the AWS Marketplace.
The following steps will allow you to deploy the Weave GitOps product to an EKS cluster via a Helm Chart.
These instructions presume you already have installed kubectl, eksctl, helm and the Helm S3 Plugin.
To deploy the managed Weave GitOps solution, first subscribe to the product on AWS Marketplace.
Note: it may take ~20 minutes for your Subscription to become live and deployable.
"},{"location":"open-source/aws-marketplace/#step-2-configure-an-eks-cluster","title":"Step 2: Configure an EKS Cluster","text":"Create a new EKS ClusterUse an existing EKS ClusterIf you do not have a cluster on EKS, you can use eksctl to create one.
Copy the contents of the sample file below into cluster-config.yaml and replace the placeholder values with your settings. See the eksctl documentation for more configuration options.
---\napiVersion: eksctl.io/v1alpha5\nkind: ClusterConfig\nmetadata:\nname: CLUSTER_NAME # Change this\nregion: REGION # Change this\n\n# This section is required\niam:\nwithOIDC: true\nserviceAccounts:\n- metadata:\nname: wego-service-account # Altering this will require a corresponding change in a later command\nnamespace: flux-system\nroleOnly: true\nattachPolicy:\nVersion: \"2012-10-17\"\nStatement:\n- Effect: Allow\nAction:\n- \"aws-marketplace:RegisterUsage\"\nResource: '*'\n\n# This section will create a single Managed nodegroup with one node.\n# Edit or remove as desired.\nmanagedNodeGroups:\n- name: ng1\ninstanceType: m5.large\ndesiredCapacity: 1\nCreate the cluster:
eksctl create cluster -f cluster-config.yaml\nIn order to use the Weave GitOps container product, your cluster must be configured to run containers with the correct IAM Policies.
The recommended way to do this is via IRSA.
Use this eksctl configuration below (replacing the placeholder values) to: - Associate an OIDC provider - Create the required service account ARN
Save the example below as oidc-config.yaml
---\napiVersion: eksctl.io/v1alpha5\nkind: ClusterConfig\nmetadata:\nname: CLUSTER_NAME # Change this\nregion: REGION # Change this\n\n# This section is required\niam:\nwithOIDC: true\nserviceAccounts:\n- metadata:\nname: wego-service-account # Altering this will require a corresponding change in a later command\nnamespace: flux-system\nroleOnly: true\nattachPolicy:\nVersion: \"2012-10-17\"\nStatement:\n- Effect: Allow\nAction:\n- \"aws-marketplace:RegisterUsage\"\nResource: '*'\neksctl utils associate-iam-oidc-provider -f oidc-config.yaml --approve\neksctl create iamserviceaccount -f oidc-config.yaml --approve\nFirst retrieve the ARN of the IAM role which you created for the wego-service-account:
# replace the placeholder values with your configuration\n# if you changed the service account name from wego-service-account, update that in the command\nexport SA_ARN=$(eksctl get iamserviceaccount --cluster <cluster-name> --region <region> | awk '/wego-service-account/ {print $3}')\n\necho $SA_ARN\n# should return\n# arn:aws:iam::<account-id>:role/eksctl-<cluster-name>-addon-iamserviceaccount-xxx-Role1-1N41MLVQEWUOF\nThis value will also be discoverable in your IAM console, and in the Outputs of the Cloud Formation template which created it.
"},{"location":"open-source/aws-marketplace/#step-4-install-weave-gitops","title":"Step 4: Install Weave GitOps","text":"Copy the Chart URL from the Usage Instructions in AWS Marketplace, or download the file from the Deployment template to your workstation.
To be able to log in to your new installation, you need to set up authentication. Create a new file values.yaml where you set your username, and a bcrypt hash of your desired password, like so:
gitops:\nadminUser:\ncreate: true\nusername: <UPDATE>\npasswordHash: <UPDATE>\nThen install it:
Using the default Service Account NameUsing a configured Service Account Namehelm install wego <URL/PATH> \\\n--namespace=flux-system \\\n--create-namespace \\\n--set serviceAccountRole=\"$SA_ARN\" \\\n--values ./values.yaml\nhelm install wego <URL/PATH> \\\n--namespace=flux-system \\\n--create-namespace \\\n--set serviceAccountName='<name>' \\\n--set serviceAccountRole=\"$SA_ARN\" \\\n--values ./values.yaml\nRun the following from your workstation:
kubectl get pods -n flux-system\n# you should see something like the following returned\nflux-system helm-controller-5b96d94c7f-tds9n 1/1 Running 0 53s\nflux-system kustomize-controller-8467b8b884-x2cpd 1/1 Running 0 53s\nflux-system notification-controller-55f94bc746-ggmwc 1/1 Running 0 53s\nflux-system source-controller-78bfb8576-stnr5 1/1 Running 0 53s\nflux-system wego-metering-f7jqp 1/1 Running 0 53s\nflux-system ww-gitops-weave-gitops-5bdc9f7744-vkh65 1/1 Running 0 53s\nYour Weave GitOps installation is now ready!
"},{"location":"open-source/deploy-oss/","title":"Step 3: Deploy an Application","text":"Now that you have a feel for how to navigate the dashboard, let's deploy a new application. In this section we will use podinfo as our sample web application.
"},{"location":"open-source/deploy-oss/#deploying-podinfo","title":"Deploying podinfo","text":"git clone https://github.com/$GITHUB_USER/fleet-infra\ncd fleet-infra\nflux create source git podinfo \\\n --url=https://github.com/stefanprodan/podinfo \\\n --branch=master \\\n --interval=30s \\\n --export > ./clusters/management/podinfo-source.yaml\nMore information about GitRepository is available here.
If you get stuck here, try the ls command to list your files and directories. If that doesn\u2019t work, try ls -l ./clusters.
git add -A && git commit -m \"Add podinfo source\"\ngit push\nflux create kustomization podinfo \\\n --target-namespace=flux-system \\\n --source=podinfo \\\n --path=\"./kustomize\" \\\n --prune=true \\\n --interval=5m \\\n --export > ./clusters/management/podinfo-kustomization.yaml\ngit add -A && git commit -m \"Add podinfo kustomization\"\ngit push\nFlux will detect the updated fleet-infra and add podinfo. Navigate back to the dashboard to make sure that the podinfo application appears.
Click on podinfo to find details about the deployment. There should be two pods available.
Info
Podinfo comes with a HorizontalPodAutoscaler, which uses the metrics-server. We don't use the metrics-server in this tutorial, but note that it's the reason why HorizontalPodAutoscaler will report as Not ready in your dashboard. We recommend ignoring the warning.
To customize a deployment from a repository you don\u2019t control, you can use Flux in-line patches. The following example shows how to use in-line patches to change the podinfo deployment.
---\napiVersion: kustomize.toolkit.fluxcd.io/v1beta2\nkind: Kustomization\nmetadata:\nname: podinfo\nnamespace: flux-system\nspec:\ninterval: 60m0s\npath: ./kustomize\nprune: true\nsourceRef:\nkind: GitRepository\nname: podinfo\ntargetNamespace: flux-system\n// highlight-start\npatches:\n- patch: |-\napiVersion: autoscaling/v2beta2\nkind: HorizontalPodAutoscaler\nmetadata:\nname: podinfo\nspec:\nminReplicas: 3\ntarget:\nname: podinfo\nkind: HorizontalPodAutoscaler\n// highlight-end\ngit add -A && git commit -m \"Increase podinfo minimum replicas\"\ngit push\nSuspending updates to a kustomization allows you to directly edit objects applied from a kustomization, without your changes being reverted by the state in Git.
To suspend updates for a kustomization, from the details page, click on the suspend button at the top, and you should see it be suspended:
This shows in the applications view with a yellow warning status indicating it is now suspended
To resume updates, go back to the details page, click the resume button, and after a few seconds reconsolidation will continue.
"},{"location":"open-source/deploy-oss/#delete-podinfo","title":"Delete Podinfo","text":"To delete Podinfo in the GitOps way, run this command from the root of your working directory:
rm ./clusters/management/podinfo-kustomization.yaml\n rm ./clusters/management/podinfo-source.yaml\n git add -A && git commit -m \"Remove podinfo kustomization and source\"\n git push\nCongratulations \ud83c\udf89\ud83c\udf89\ud83c\udf89
You've now completed the getting started guide. We welcome any and all feedback, so please let us know how we could have made your experience better.
"},{"location":"open-source/install-oss/","title":"Step 1: Install Weave GitOps Open Source on Your Cluster","text":"Tip
These instructions only apply to Weave GitOps Open Source. To install Weave GitOps Enterprise, go here.
This page covers Weave GitOps Open Source installation and is adapted from the Flux - Getting Started guide.
If you haven't already, please check out our Introduction to Weave GitOps page for additional information about Weave GitOps Open Source as well as our Enterprise version.
"},{"location":"open-source/install-oss/#prerequisites","title":"Prerequisites","text":"Before you can install Weave GitOps Open Source, you will need:
We also recommend taking a look at the Flux Core Concepts page if you need to brush up on terminology.
"},{"location":"open-source/install-oss/#check-your-clusters-kubernetes-version","title":"Check your Cluster's Kubernetes Version","text":"No matter which version of Weave GitOps you install, you need to have a Kubernetes cluster up and running. We test Weave GitOps against the latest supported Kubernetes releases.
Note that the version of Flux that you use might impose further minimum version requirements.
"},{"location":"open-source/install-oss/#install-flux","title":"Install Flux","text":"Weave GitOps is an extension to Flux. Therefore, it requires that Flux 0.32 or a later version has already been installed on your Kubernetes cluster. Full documentation is available here.
In this section we are going to do the following:
Let's get into it...
"},{"location":"open-source/install-oss/#install-the-flux-cli","title":"Install the Flux CLI","text":"brew install fluxcd/tap/flux\nTo upgrade to the latest version, run this command:
brew upgrade fluxcd/tap/flux\nWe recommend upgrading the CLI before running bootstrap to upgrade the controllers with flux bootstrap.
Find which version is installed with flux -v, and use that for flux bootstrap --version=v<CLI-VERSION>.
With Bash, you can run sudo curl -s https://fluxcd.io/install.sh | sudo FLUX_VERSION=<VERSION> bash.
Tip
If you want to install an older version of Flux CLI, you can download the binary for your OS from the releases page.
For other installation methods, see the relevant Flux documentation.
"},{"location":"open-source/install-oss/#export-your-credentials","title":"Export your credentials","text":"Ensure your PAT has repo scope.
export GITHUB_TOKEN=<your-token>\nexport GITHUB_USER=<your-username>\nflux check --pre\nThe output is similar to:
\u25ba checking prerequisites\n\u2714 kubernetes 1.22.2 >=1.20.6\n\u2714 prerequisites checks passed\nflux bootstrap command","text":"flux bootstrap creates a flux system folder in your repository that includes the manifests Flux needs to operate. It also generates a key value pair for Flux to access the repo.
The command below assumes the Git provider is github. If you would rather use GitLab, change this to gitlab.
flux bootstrap github \\\n --owner=$GITHUB_USER \\\n --repository=fleet-infra \\\n --branch=main \\\n --path=./clusters/my-cluster \\\n --personal \\\n --components-extra image-reflector-controller,image-automation-controller\nFull installation documentation, including how to work with other Git providers, is available here.
"},{"location":"open-source/install-oss/#install-the-gitops-cli","title":"Install thegitops CLI","text":"Weave GitOps includes a command-line interface to help users create and manage resources. The gitops CLI is currently supported on Mac (x86 and Arm) and Linux, including Windows Subsystem for Linux (WSL). Windows support is a planned enhancement.
There are multiple ways to install the gitops CLI:
curl --silent --location \"https://github.com/weaveworks/weave-gitops/releases/download/v0.36.0/gitops-$(uname)-$(uname -m).tar.gz\" | tar xz -C /tmp\nsudo mv /tmp/gitops /usr/local/bin\ngitops version\nbrew tap weaveworks/tap\nbrew install weaveworks/tap/gitops\nIn this section we will:
git clone https://github.com/$GITHUB_USER/fleet-infra\ncd fleet-infra\nIf you have difficulty saving the YAML to the correct path, run the command mkdir -p ./clusters/my-cluster.
Run the following command, which will create a HelmRepository and HelmRelease to deploy Weave GitOps:
PASSWORD=\"<A new password you create, removing the brackets and including the quotation marks>\"\ngitops create dashboard ww-gitops \\\n --password=$PASSWORD \\\n --export > ./clusters/my-cluster/weave-gitops-dashboard.yaml\nWarning
This command stores a hash of a password. This is relatively safe for demo and testing purposes, but we strongly recommend using a more secure method of storing secrets (such as Flux's SOPS integration) for production systems.
Our docs on securing access to the dashboard provide additional guidance and alternative login methods.
You will use the password you've just created when you've finished Weave GitOps Open Source installation and are ready to login to the dashboard UI.
Tip
If you need to customize the Weave GitOps Helm release, you can use the --values CLI flag to supply one or more values files.
weave-gitops-dashboard.yaml to the fleet-infra repository","text":"git add -A && git commit -m \"Add Weave GitOps Dashboard\"\ngit push\nNote: this wont be instantaneous. Give the Flux controllers a couple of minutes to pull the latest commit.
kubectl get pods -n flux-system\nYou should see something similar to:
NAME READY STATUS RESTARTS AGE\nhelm-controller-5bfd65cd5f-gj5sz 1/1 Running 0 10m\nkustomize-controller-6f44c8d499-s425n 1/1 Running 0 10m\nnotification-controller-844df5f694-2pfcs 1/1 Running 0 10m\nsource-controller-6b6c7bc4bb-ng96p 1/1 Running 0 10m\nww-gitops-weave-gitops-86b645c9c6-k9ftg 1/1 Running 0 5m\nIf you wait for a while and still nothing happens, it might be that your manifests haven\u2019t been exported to the repository. This means that Weave GitOps won't install.
Tip
You can use the Weave GitOps Helm Chart to customize your installation. Find the full Chart reference here.
"},{"location":"open-source/install-oss/#next-steps","title":"Next steps","text":"Now let's explore the Weave GitOps Open Source UI. Then, we'll deploy an application.
"},{"location":"open-source/run-ui-subpath/","title":"Optional: Running the UI on a Subpath","text":""},{"location":"open-source/run-ui-subpath/#running-the-ui-on-a-subpath","title":"Running the UI on a subpath","text":"By default, the UI is served on the root path /. It is possible to run the UI on a subpath, for example /weave-gitops. This is useful if you want to run weave-gitops alongside other applications on the same domain.
To run the UI on a subpath, you need to set the --route-prefix flag on the weave-gitops server. For example, if you want to run the UI on /weave-gitops, you can set the flag to --route-prefix=/weave-gitops.
To set the flag we use the additionalArgs field in the spec.values section of the weave-gitops HelmRelease.
spec:\nvalues:\nadditionalArgs:\n- --route-prefix=/weave-gitops\nIngress is a Kubernetes resource that allows you to expose your application to the internet. Please refer to the Kubernetes documentation for more information about a complete Ingress configuration. It often depends on the Kubernetes provider you are using and your particular setup.
The Weave GitOps Helm chart can generate an Ingress resource to integrate with the ingress controller you have configured for your cluster. To enable ingress generation set the ingress.enabled field to true.
spec:\nvalues:\ningress:\nenabled: true\nhosts:\n- host: \"\"\npaths:\n- path: /wego # set the path to `/` if you have not set the `--route-prefix` flag \npathType: Prefix\nSee the Helm chart reference for a list of all supported ingress options.
"},{"location":"open-source/ui-oss/","title":"Step 2: Explore the Weave GitOps Open Source UI","text":"The Weave GitOps user interface enables you to manage and view all of your applications in one place. This documentation gives you an overview of the Weave GitOps Open Source UI.
Tip
To check out Weave GitOps Enterprise's UI, which provides an even richer user experience, please contact sales@weave.works.
"},{"location":"open-source/ui-oss/#overview","title":"Overview","text":"A quick preview of what the Weave GitOps Open Source UI provides: * an Applications view that shows summary information from\u00a0Kustomization\u00a0and\u00a0HelmRelease\u00a0objects so that you can quickly understand the state of your deployments across a cluster. * a Sources view that shows summary information from\u00a0gitrepository,\u00a0helmrepository\u00a0and\u00a0bucket\u00a0objects and tells you the current status of resources that are synchronizing content from where you\u2019ve declared the desired state of your system\u2014for example, Git repositories. * a Flux Runtime view that provides the status of the GitOps engine that continuously reconciles your desired and live state. It shows your installed GitOps Toolkit Controllers and version. * an Image Automation view that reduces GitOps friction, particularly in non-production environments, by enabling you to discover repositories, policies, and updates on your cluster. Deploy the latest image in a dev or staging environment with minimal fuss, and keep your platform updated with the latest approved versions\u2014for example, patch releases to reduce exposure to CVEs. Auto-deploy when approval is gated before the image is added to an internal registry. * A Notifications View that leverages Flux's notification controller to show which notifications are already configured within the UI. This enables WeGO users to set up and receive notifications from Weave GitOps. Here you can find the list of providers. If you\u2019re a platform operator, this view will help you to understand your egress topology across clusters so you\u2019ll know where events are being sent beyond your clusters. * multiple views for debugging. * a dark mode option.
It also enables you to: * sync your latest Git commits directly from the UI * leverage Kubernetes RBAC to control permissions in the dashboard
Let's dive in.
"},{"location":"open-source/ui-oss/#login-to-the-gitops-dashboard","title":"Login to the GitOps Dashboard","text":"First, expose the service running on the cluster with this command:
kubectl port-forward svc/ww-gitops-weave-gitops -n flux-system 9001:9001\nNext, open the dashboard and login using either the emergency cluster user or OIDC, based on your configuration. (Note: The same directions for WGE apply to OSS for this step.) If you followed the example above, the emergency user will be configured with the username set to admin. This means that you can use \u201cadmin\u201d as your user name, and the password that you set earlier during installation as $PASSWORD.
The label of the OIDC button on the login screen is configurable via a feature flag environment variable. This can give your users a more familiar experience when logging in.
Adjust the configuration in the Helm values.yaml file or the spec.values section of the Weave GitOps HelmRelease resource:
envVars:\n- name: WEAVE_GITOPS_FEATURE_OIDC_BUTTON_LABEL\nvalue: \"Login with ACME\"\nUpon login you're taken to the Applications view, which allows you to quickly understand the state of your deployments and shows summary information from Kustomization and HelmRelease objects. You can apply dark mode using the toggle switch in the top right corner.
In the above screenshot you can see: - two Kustomizations called podinfo and canaries corresponding to the applications with the same names. The source referenced by podinfo is shipping-service-podinfo which has been verified whereas the one referenced by canaries does not have verification set up. - three HelmReleases called weave-gitops-enterprise, tf-controller and podinfo which deploys the respective Helm Charts.
The table view shows you the reported status so you can understand whether a reconciliation has been successful, and when it was last updated. You can also see where the Flux objects are deployed, which Source object they are reconciling from and whether or not that Source is verified (this requires verification to have been set up for the source). Clicking the name of the Source will take you to a detail view for the given Source object. The view automatically updates every few seconds so you know the current state of your system.
Tip
For more information about Sources, please take a look at the Flux documentation.
For information on Source verification, you can check: - Flux documentation - GitRepository verification - Flux documentation - OCIRepository verification
If verification is not set up for the repository, this will appear blank in the UI.
More actions you can take: * Click the magnifying glass icon to search for and filter objects by Name. * Filter by Type by clicking the strawberry icon to its right. * Click the Name of an object to get a detailed view for the given Kustomization or HelmRelease. (You'll see this again in the Sources view.) * In the main Applications view, you can use the checkbox to the left of your listed applications to select them and perform actions from the actions menu at the top. These actions are Sync (reconcile), Suspend, and Resume, and they affect Flux resources.
Let's explore the flux-system Kustomization. Navigate back to the Applications view, and click on the flux-system object.
It might take a few moments for the data to load. Once it does, you should get a result that resembles the above screenshot. Here you can find key information about how the resource is defined: * which Source it is reading from * the latest applied commit * the exact path with the Source repository that is being deployed * the Interval where Flux will look to reconcile any differences between the declared and live state. For example, if a kubectl patch has been applied on the cluster, it will effectively be reverted. If a longer error message is reported by this object, you'll be able to see it in its entirety on this page.
Underneath the summary information you'll find:
Events tab
Reconciliation Graph tab
Yaml tab
"},{"location":"open-source/ui-oss/#the-sources-view","title":"The Sources View","text":"In the left-hand menu of the UI, click on the Sources view. This will show you where Flux pulls its application definitions from\u2014for example, Git repositories\u2014and the current state of that synchronization. Sources shows summary information from GitRepository, HelmRepository, HelmChart, and Bucket objects.
In the above screenshot you can see: - a GitRepository called shipping-service-podinfo - an OCIRepository called podinfo-oci
These have both had verification set up on them which has been completed successfully.
The Sources table view displays information about status so that you can see whether Flux has been able to successfully pull from a given source, and which specific commit was last detected. It shows you key information like the Interval\u2014namely, how frequently Flux will check for updates in a given source location. You can also see whether or not that source is verified (if this is something that you have set up for the specific source).
Actions you can take: * Apply filtering as you did the Applications view. * Click a URL to navigate to a given source\u2014i.e. a repository in GitHub\u2014or the Name of a Source to view more details about it.
Go back to the Details tab, and click GitRepository/flux-system from the summary at the top of the page.
As with an Application detail view, you can see key information about how the resource is defined.
"},{"location":"open-source/ui-oss/#the-image-automation-view","title":"The Image Automation View","text":"Maybe you're an app developer who wants to deploy the latest image in a dev/staging environment with as minimal fuss as possible and reduce GitOps friction. Or you might be a platform engineer who wants to keep your platform up-to-date with the latest approved versions\u2014for example, patch releases to reduce exposure to CVEs\u2014or auto-deploy when approval is gated before adding an image to an internal registry. The Image Automation view can help.
WeGO's Image Automation view allows users to configure automatic updates to their workloads based on the detection of a new image tag in a repository. For application developers, this means faster deployments and shorter feedback cycles to easily verify changes to an application in a Kubernetes environment. The view still supports GitOps workflows as the changes are committed back to Git\u2014either to the branch already reconciled by Flux, or to an alternative branch so that a Pull Request can be generated and peer review can occur.
Image Automation refers to Flux's ability to update the image tag specified in a manifest based on detection of a newer image and automatically deploy to a cluster. It involves three required objects\u2014ImageRepositories, ImagePolicies, and ImageUpdateAutomations\u2014which WeGO OSS users can discover on their clusters. Users can also view object details either through a YAML-like view, as we do for most non-Flux objects, or a details view. The UI makes it possible to suspend or resume ImageRepositories and ImageUpdateAutomations so that Flux stops looking for new updates or committing these to Git. Also, the UI shows whether all required resources are configured and assists with Image Policy to show the latest image.
ImageRepositories, ImagePolicies, and ImageUpdateAutomations are used by Flux's Image Automation Controllers. The Image Reflector controller and the Image Automation controller work together to update a Git repository when new container images are available. In WeGO OSS, if the image-reflector-controller and or image-automation-controller are not installed on a cluster, a warning message will display.
If you make a mistake configuring one of the resources, you can use WeGO to easily trace from the Image Repository scan, see whether it is able to select the image based on the Image Policy, and detect whether an Image Update has successfully run. This provides greater visibility into the machinery provided by Flux and enables quicker troubleshooting than what's possible by hunting via the Flux CLI. App devs can triage issues without depending on their platform teams.
"},{"location":"open-source/ui-oss/#the-flux-runtime-view","title":"The Flux Runtime View","text":"Let's go back to the left-hand menu of the UI and click on Flux Runtime. This view provides information on the GitOps engine, which continuously reconciles your desired and live state, and helps users to know which apiVersion to use in manifests. It comes with two tabs: one for controllers, and other for custom resource definitions (CRDs).
The Controllers tab shows your installed GitOps Toolkit Controllers and their version.
By default, flux bootstrap will install the following controllers: - helm-controller - kustomize-controller - notification-controller - source-controller
From this view you can see whether the controllers are healthy and which version of a given component is currently deployed.
"},{"location":"open-source/ui-oss/#crds","title":"CRDs","text":"The CRD tab lists the custom resources that the GitOps Toolkit Controllers use. This allows you to see which resources you will be able to create.
"},{"location":"open-source/ui-oss/#moving-on","title":"Moving On","text":"Now that we are familiar with the dashboard, let's deploy a new application .
"},{"location":"pipelines/","title":"Pipelines ENTERPRISE","text":"Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
Weave GitOps Enterprise Pipelines enables teams to increase the velocity, stability, and security of software systems via automated deployment pipelines. It provides insights into new application versions that are being rolled out across clusters and environments, which allows you to implement security guardrails and track metrics to assess if the application is working as desired. In instances of failures, the change is abandoned with an automatic rollout of the older version.
With Pipelines, you define a release pipeline for a given application as a custom resource. The pipeline can comprise any number of environments through which an application is expected to be deployed. Push a change to your application in your dev environment, for example, and watch the update roll out across staging and production environments all from a single PR (or an external process like Jenkins)\u2014with Weave GitOps Enterprise orchestrating everything.
Designed with flexibility in mind, Pipelines can be easily integrated within your existing CI setup\u2014for example, CircleCI, Jenkins, Tekton, or GitHub Actions.
"},{"location":"pipelines/#benefits-to-developers","title":"Benefits to Developers","text":"The Pipelines feature: - reduces toil and errors when setting up a new pipeline or reproducing previous pipelines through YAML constructs - saves time and overhead with automated code rollout from one environment to another, with minimal intervention from the Ops team - enables users to observe code progression and track application versions through different environments from the Weave GitOps UI - streamlines code deployment from one environment to another, and minimizes friction between application development and Ops teams - enables you to easily define which Helm charts are part of the environments you create\u2014saving lots of time through automated package management
Now that you know what delivery pipelines can do for you, follow the guide to get started.
"},{"location":"pipelines/authorization/","title":"Authorization ENTERPRISE","text":"Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
To view pipelines, users need read access to the pipeline resource and the underlying application resources. This sample configuration shows a recommended way to configure RBAC to provide such access. The pipeline-reader role and the search-pipeline-reader role-binding allow a group search-developer to access pipeline resources within the search namespace.
apiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRole\nmetadata:\nname: pipeline-reader\nrules:\n- apiGroups: [ \"pipelines.weave.works\" ]\nresources: [ \"pipelines\" ]\nverbs: [ \"get\", \"list\", \"watch\"]\n- apiGroups: [\"helm.toolkit.fluxcd.io\"]\nresources: [ \"helmreleases\" ]\nverbs: [ \"get\", \"list\", \"watch\"]\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: RoleBinding\nmetadata:\nname: search-pipeline-reader\nnamespace: search\nsubjects:\n- kind: Group\nname: search-developer\napiGroup: rbac.authorization.k8s.io\nroleRef:\nkind: ClusterRole\nname: pipeline-reader\napiGroup: rbac.authorization.k8s.io\nWarning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
"},{"location":"pipelines/pipelines-getting-started/#prerequisites","title":"Prerequisites","text":"Before using Pipelines, please ensure that: - You have Weave GitOps Enterprise installed on a cluster. - You have configured Weave GitOps Enterprise RBAC for Pipelines. - The Pipelines feature flag enablePipelines has been enabled. This flag is part of the Weave GitOps Enterprise Helm chart values and is enabled by default. - Any leaf clusters running workloads that you need to visualise using Pipelines have been added to Weave GitOps Enterprise. - You have exposed the promotion webhook on the management cluster and leaf clusters can reach that webhook endpoint over the network.
A pipeline allows you to define the route your application is taking, so that you can get it to production. Three main concepts are at play: - the application to deliver - the environments that your app will go through on its way to production (general). An environment describes the different stages of a pipeline and consists of one or more deployment targets. - the deployment targets, the clusters that each environment has. A deployment target consists of a namespace and a GitOpsCluster reference and is used to specify where the application is running in your fleet.
You can define a delivery pipeline using a Pipeline custom resource. An example of such a CR is shown here:
---\napiVersion: pipelines.weave.works/v1alpha1\nkind: Pipeline\nmetadata:\nname: podinfo-02\nnamespace: flux-system\nspec:\nappRef:\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nname: podinfo\nenvironments:\n- name: dev\ntargets:\n- namespace: podinfo-02-dev\nclusterRef:\nkind: GitopsCluster\nname: dev\nnamespace: flux-system\n- name: test\ntargets:\n- namespace: podinfo-02-qa\nclusterRef:\nkind: GitopsCluster\nname: dev\nnamespace: flux-system\n- namespace: podinfo-02-perf\nclusterRef:\nkind: GitopsCluster\nname: dev\nnamespace: flux-system\n- name: prod\ntargets:\n- namespace: podinfo-02-prod\nclusterRef:\nkind: GitopsCluster\nname: prod\nnamespace: flux-system\nIn the example above, the podinfo application is delivered to a traditional pipeline composed of dev, test, and prod environments. In this case, the test environment consists of two deployment targets, qa and perf. This is to indicate that, although both targets are part of the same stage (testing), they can evolve separately and may run different versions of the application. Note that two clusters, dev and prod, are used for the environments; both are defined in the flux-system namespace.
For more details about the spec of a pipeline, go here.
"},{"location":"pipelines/pipelines-getting-started/#view-your-list-of-pipelines","title":"View Your List of Pipelines","text":"Once Flux has reconciled your pipeline, you can navigate to the Pipelines view in the WGE UI to see the list of pipelines to which you have access.
For each pipeline, the WGE UI shows a simplified view with the application Type and Environments it goes through.
Once you have selected a pipeline from the list, navigate to its details view where you can see the current status of your application by environment and deployment target.
"},{"location":"pipelines/pipelines-templates/","title":"Using GitOpsTemplates for Pipelines ENTERPRISE","text":"To create new Pipelines and their required resources from within Weave GitOps Enterprise, you can leverage GitOpsTemplates, which help platform teams scale for developer self-service.
This document provides example configuration that you can adapt and use within your own organization, based on your tenancy model.
We will cover the creation of:
Secrets, required for authentication and authorization between leaf and management clusters as well as to Git, are out of scope for this document and must be handled by your chosen secret management solution.
For advice on Secrets Management, refer to the Flux guide.
Templates can include a single resource or multiple resources, depending on your use case. For example, you may want to only create the Pipeline custom resource to associate existing HelmReleases. Or, you can create the HelmReleases, notification controller resources, and Pipeline all in a single template. They are highly customizable to meet the needs of your teams.
"},{"location":"pipelines/pipelines-templates/#adding-new-resources-from-within-the-weave-gitops-enterprise-dashboard","title":"Adding New Resources From Within the Weave GitOps Enterprise Dashboard","text":"GitOpsTemplates are custom resources installed onto a management cluster where Weave GitOps Enterprise resides. To add a new Pipeline, click Create a Pipeline from within the Pipeline view. This will take you to a pre-filtered list of templates with the label: weave.works/template-type: pipeline.
The Templates view (shown below) lists all templates for which a given user has the appropriate permission to view. You can install GitOpsTemplates into different namespaces and apply standard Kubernetes RBAC to limit which teams can utilize which templates. You can also configure policy to enforce permitted values within a template.
This section provides examples to help you build your own templates for Pipelines.
"},{"location":"pipelines/pipelines-templates/#pipeline-visualization-only","title":"Pipeline: Visualization Only","text":"Included Sample
This default template is shipped with Weave GitOps Enterprise to help you get started with Pipelines.
For flexibility, this allows the template user to specify the names of the clusters where the application is deployed, and to vary the namespace per cluster. This works even in a tenancy model where environments coexist on the same cluster and use namespaces for isolation.
Expand to view example template---\napiVersion: templates.weave.works/v1alpha2\nkind: GitOpsTemplate\nmetadata:\nname: pipeline-sample\nnamespace: default # Namespace where the GitOpsTemplate is installed, consider that a team will need READ access to this namespace and the custom resource\nlabels:\nweave.works/template-type: pipeline\nspec:\ndescription: Sample Pipeline showing visualization of two helm releases across two environments.\nparams:\n- name: RESOURCE_NAME # This is a required parameter name to enable Weave GitOps to write to your Git Repository\ndescription: Name of the Pipeline\n- name: RESOURCE_NAMESPACE\ndescription: Namespace for the Pipeline on the management cluster\ndefault: flux-system # default values make it easier for users to fill in a template\n- name: FIRST_CLUSTER_NAME\ndescription: Name of GitopsCluster object for the first environment\n- name: FIRST_CLUSTER_NAMESPACE\ndescription: Namespace where this object exists\ndefault: default\n- name: FIRST_APPLICATION_NAME\ndescription: Name of the HelmRelease for your application in the first environment\n- name: FIRST_APPLICATION_NAMESPACE\ndescription: Namespace for this application\ndefault: flux-system\n- name: SECOND_CLUSTER_NAME\ndescription: Name of GitopsCluster object for the second environment\n- name: SECOND_CLUSTER_NAMESPACE\ndescription: Namespace where this object exists\ndefault: default\n- name: SECOND_APPLICATION_NAME\ndescription: Name of the HelmRelease for your application in the second environment\n- name: SECOND_APPLICATION_NAMESPACE\ndescription: Namespace for this application\ndefault: flux-system\nresourcetemplates:\n- content:\n- apiVersion: pipelines.weave.works/v1alpha1\nkind: Pipeline\nmetadata:\nname: ${RESOURCE_NAME}\nnamespace: ${RESOURCE_NAMESPACE}\nspec:\nappRef:\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nname: ${APPLICATION_NAME}\nenvironments:\n- name: First-Environment\ntargets:\n- namespace: ${FIRST_APPLICATION_NAMESPACE}\nclusterRef:\nkind: GitopsCluster\nname: ${FIRST_CLUSTER_NAME}\nnamespace: ${FIRST_CLUSTER_NAMESPACE}\n- name: Second-Environment\ntargets:\n- namespace: ${SECOND_APPLICATION_NAMESPACE}\nclusterRef:\nkind: GitopsCluster\nname: ${SECOND_CLUSTER_NAME}\nnamespace: ${SECOND_CLUSTER_NAMESPACE}\nThis example extends the above to add a promotion strategy. In this case, it will raise a pull request to update the application version in subsequent environments.
Expand to view example template---\napiVersion: templates.weave.works/v1alpha2\nkind: GitOpsTemplate\nmetadata:\nname: pipeline-sample\nnamespace: default\nlabels:\nweave.works/template-type: pipeline\nspec:\ndescription: Sample Pipeline showing visualization of two helm releases across two environments.\nparams:\n- name: RESOURCE_NAME\ndescription: Name of the Pipeline\n- name: RESOURCE_NAMESPACE\ndescription: Namespace for the Pipeline on the management cluster\ndefault: flux-system\n- name: FIRST_CLUSTER_NAME\ndescription: Name of GitopsCluster object for the first environment\n- name: FIRST_CLUSTER_NAMESPACE\ndescription: Namespace where this object exists\ndefault: default\n- name: FIRST_APPLICATION_NAME\ndescription: Name of the HelmRelease for your application in the first environment\n- name: FIRST_APPLICATION_NAMESPACE\ndescription: Namespace for this application\ndefault: flux-system\n- name: SECOND_CLUSTER_NAME\ndescription: Name of GitopsCluster object for the second environment\n- name: SECOND_CLUSTER_NAMESPACE\ndescription: Namespace where this object exists\ndefault: default\n- name: SECOND_APPLICATION_NAME\ndescription: Name of the HelmRelease for your application in the second environment\n- name: SECOND_APPLICATION_NAMESPACE\ndescription: Namespace for this application\ndefault: flux-system\n- name: APPLICATION_REPO_URL\ndescription: URL for the git repository containing the HelmRelease objects\n- name: APPLICATION_REPO_BRANCH\ndescription: Branch to update with new version\n- name: GIT_CREDENTIALS_SECRET\ndescription: Name of the secret in RESOURCE_NAMESPACE containing credentials to create pull requests\nresourcetemplates:\n- content:\n- apiVersion: pipelines.weave.works/v1alpha1\nkind: Pipeline\nmetadata:\nname: ${RESOURCE_NAME}\nnamespace: ${RESOURCE_NAMESPACE}\nspec:\nappRef:\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nname: ${APPLICATION_NAME}\nenvironments:\n- name: First-Environment\ntargets:\n- namespace: ${FIRST_APPLICATION_NAMESPACE}\nclusterRef:\nkind: GitopsCluster\nname: ${FIRST_CLUSTER_NAME}\nnamespace: ${FIRST_CLUSTER_NAMESPACE}\n- name: Second-Environment\ntargets:\n- namespace: ${SECOND_APPLICATION_NAMESPACE}\nclusterRef:\nkind: GitopsCluster\nname: ${SECOND_CLUSTER_NAME}\nnamespace: ${SECOND_CLUSTER_NAMESPACE}\npromotion:\npull-request:\nurl: ${APPLICATION_REPO_URL}\nbaseBranch: ${APPLICATION_REPO_BRANCH}\nsecretRef:\nname: ${GIT_CREDENTIALS_SECRET}\nFor guidance on configuring credentials, find instructions in the Promoting Applications documentation.
"},{"location":"pipelines/pipelines-templates/#promotion-marker-added-to-helmrelease-in-second-environment","title":"Promotion Marker Added to HelmRelease inSecond-Environment","text":"You must add a comment to the HelmRelease or Kustomization patch where the spec.chart.spec.version is defined. For example, if the values used in the above template were as follows:
RESOURCE_NAME=my-app\nRESOURCE_NAMESPACE=pipeline-01\nThen the marker would be:
# {\"$promotion\": \"pipeline-01:my-app:Second-Environment\"}\nFind more guidance on adding markers here.
"},{"location":"pipelines/pipelines-templates/#alerts-and-providers","title":"Alerts and Providers","text":"This example shows you how you can configure multiple resources in a single template and simplify creation through common naming strategies. The notification controller communicates update events from the leaf clusters where applications are deployed to the management cluster, where the Pipeline Controller resides and orchestrates.
For the Alert, this template filters events to detect when an update has occurred. Depending on your use case, you can use different filtering.
For the Provider, this template uses authenticated (HMAC) communication to the promotion endpoint, where a secret must be present on both the management cluster and the leaf cluster(s). For simplicity's sake, you can use a generic provider instead; this will not require the secret.
---\napiVersion: templates.weave.works/v1alpha2\nkind: GitOpsTemplate\nmetadata:\nname: pipeline-notification-resources\nnamespace: default\nlabels:\nweave.works/template-type: application # These are generic Flux resources rather than Pipeline-specific\nspec:\ndescription: Creates flux notification controller resources for a cluster, required for promoting applications via pipelines.\nparams:\n- name: RESOURCE_NAME\ndescription: Name for the generated objects, should match the target Application (HelmRelease) name.\n- name: RESOURCE_NAMESPACE\ndescription: Namespace for the generated objects, should match the target Application (HelmRelease) namespace.\n- name: PROMOTION_HOST\ndescription: Host for the promotion webhook on the management cluster, i.e. \"promotions.example.org\"\n- name: SECRET_REF\ndescription: Name of the secret containing HMAC key in the token field\n- name: ENV_NAME\ndescription: Environment the cluster is a part of within a pipeline.\nresourcetemplates:\n- content:\n- apiVersion: notification.toolkit.fluxcd.io/v1beta1\nkind: Provider\nmetadata:\nname: ${RESOURCE_NAME}\nnamespace: ${RESOURCE_NAMESPACE}\nspec:\naddress: http://${PROMOTION_HOST}/promotion/${APP_NAME}/${ENV_NAME}\ntype: generic-hmac\nsecretRef: ${SECRET_REF}\n- apiVersion: notification.toolkit.fluxcd.io/v1beta1\nkind: Alert\nmetadata:\nname: ${RESOURCE_NAME}\nnamespace: ${RESOURCE_NAMESPACE}\nspec:\nproviderRef:\nname: ${RESOURCE_NAME}\neventSeverity: info\neventSources:\n- kind: HelmRelease\nname: ${RESOURCE_NAME}\nexclusionList:\n- \".*upgrade.*has.*started\"\n- \".*is.*not.*ready\"\n- \"^Dependencies.*\"\ns
"},{"location":"pipelines/pipelines-templates/#summary","title":"Summary","text":"GitOpsTemplates provide a highly flexible way for platform and application teams to work together with Pipelines.
You can hard-code values, offer a range of accepted values, or allow the template consumer to provide input based on your organization's requirements.
Templates are subject to RBAC as with any Kubernetes resource, enabling you to easily control which tenants have access to which templates.
For full details on GitOpsTemplates, read our documentation.
"},{"location":"pipelines/pipelines-with-jenkins/","title":"Setting Up Pipelines to Notify a Jenkins Webhook ENTERPRISE","text":"Using Flux's Notification Controller, a Jenkins Webhook can be invoked on Pipeline promotion events.
"},{"location":"pipelines/pipelines-with-jenkins/#configuring-jenkins","title":"Configuring Jenkins","text":"To enable external callers to trigger a build on a job, an additional \"Generic Webhook Trigger\" plugin is required as Jenkins does not have this functionality built-in.
After the plugin is installed a new \"Generic Webhook Trigger\" job configuration option is available.
The only mandatory field is the \"Token\". Without this token, Jenkins will not know which build should be triggered.
"},{"location":"pipelines/pipelines-with-jenkins/#post-content-parameters","title":"Post content parameters","text":"To access fields from the pipeline event payload, each field has to be defined as a \"Post content parameters\".
Expand to see an example Promotion Event payload{\n\"involvedObject\": {\n\"kind\": \"Pipeline\",\n\"namespace\": \"flux-system\",\n\"name\": \"podinfo-pipeline\",\n\"uid\": \"74d9e3b6-0269-4c12-9051-3ce8cfb7886f\",\n\"apiVersion\": \"pipelines.weave.works/v1alpha1\",\n\"resourceVersion\": \"373617\"\n},\n\"severity\": \"info\",\n\"timestamp\": \"2023-02-08T12:34:13Z\",\n\"message\": \"Promote pipeline flux-system/podinfo-pipeline to prod with version 6.1.5\",\n\"reason\": \"Promote\",\n\"reportingController\": \"pipeline-controller\",\n\"reportingInstance\": \"chart-pipeline-controller-8549867565-7822g\"\n}\nIn order to be able to invoke a generic webhook, a notification provider has to be defined. Jenkins expects the secret token which you configured above as a GET parameter or in the request header. The secret token can be stored in a Secret:
apiVersion: v1\nkind: Secret\ntype: Opaque\nmetadata:\nname: jenkins-token\nnamespace: podinfo\nstringData:\nheaders: |\ntoken: epicsecret\nNow we can define a Notification Provider using this secret:
apiVersion: notification.toolkit.fluxcd.io/v1beta1\nkind: Provider\nmetadata:\nname: jenkins-promotion\nnamespace: podinfo\nspec:\ntype: generic\naddress: https://jenkins.domain.tld/generic-webhook-trigger/invoke\nsecretRef:\nname: jenkins-token\nWe can configure an Alert to use the jenkins-promotion provider. For example an Alert for the podinfo-pipeline in the flux-system namespace:
apiVersion: notification.toolkit.fluxcd.io/v1beta1\nkind: Alert\nmetadata:\nname: podinfo-pipeline-promotion\nnamespace: podinfo\nspec:\neventSeverity: info\neventSources:\n- kind: Pipeline\nname: podinfo-pipeline\nnamespace: flux-system\nproviderRef:\nname: jenkins-promotion\nUsing Flux's Notification Controller, a Tekton EventListener can be triggered on Pipeline promotion events.
"},{"location":"pipelines/pipelines-with-tekton/#configuring-tekton-pipelines","title":"Configuring Tekton Pipelines","text":""},{"location":"pipelines/pipelines-with-tekton/#tekton-tasks","title":"Tekton Tasks","text":"In this tutorial, we have two tasks to demonstrate how to use parameter values from the Pipeline event payload. Both tasks print out messages with information about the pipeline promotion. Each task has three parameters: name, namespace, and message.
---\napiVersion: tekton.dev/v1beta1\nkind: Task\nmetadata:\nname: hello\nnamespace: ww-pipeline\nspec:\nparams:\n- name: name\ntype: string\n- name: namespace\ntype: string\n- name: message\ntype: string\nsteps:\n- name: echo\nimage: alpine\nscript: |\n#!/bin/sh\necho \"Hello $(params.namespace)/$(params.name)!\"\necho \"Message: $(params.message)\"\n---\napiVersion: tekton.dev/v1beta1\nkind: Task\nmetadata:\nname: goodbye\nnamespace: ww-pipeline\nspec:\nparams:\n- name: name\ntype: string\n- name: namespace\ntype: string\n- name: message\ntype: string\nsteps:\n- name: goodbye\nimage: ubuntu\nscript: |\n#!/bin/bash\necho \"Goodbye $(params.namespace)/$(params.name)!\"\necho \"Message: $(params.message)\"\nThe hello-goodbye Tekton Pipeline has the same three parameters as the tasks and it passes down the values to them.
---\napiVersion: tekton.dev/v1beta1\nkind: Pipeline\nmetadata:\nname: hello-goodbye\nnamespace: ww-pipeline\nspec:\nparams:\n- name: name\ntype: string\n- name: namespace\ntype: string\n- name: message\ntype: string\ntasks:\n- name: hello\ntaskRef:\nname: hello\nparams:\n- name: namespace\nvalue: $(params.namespace)\n- name: name\nvalue: $(params.name)\n- name: message\nvalue: $(params.message)\n- name: goodbye\nrunAfter:\n- hello\ntaskRef:\nname: goodbye\nparams:\n- name: namespace\nvalue: $(params.namespace)\n- name: name\nvalue: $(params.name)\n- name: message\nvalue: $(params.message)\nIn order to be able to trigger a Pipeline from an external source, we need three Tekton resources.
A JSON payload from the Notification Service about a Pipeline promotion looks like this:
{\n\"involvedObject\": {\n\"kind\": \"Pipeline\",\n\"namespace\": \"flux-system\",\n\"name\": \"podinfo-pipeline\",\n\"uid\": \"74d9e3b6-0269-4c12-9051-3ce8cfb7886f\",\n\"apiVersion\": \"pipelines.weave.works/v1alpha1\",\n\"resourceVersion\": \"373617\"\n},\n\"severity\": \"info\",\n\"timestamp\": \"2023-02-08T12:34:13Z\",\n\"message\": \"Promote pipeline flux-system/podinfo-pipeline to prod with version 6.1.5\",\n\"reason\": \"Promote\",\n\"reportingController\": \"pipeline-controller\",\n\"reportingInstance\": \"chart-pipeline-controller-8549867565-7822g\"\n}\nIn our tasks, we are using only the involvedObject.name, involvedObject.namespace and message fields:
---\napiVersion: triggers.tekton.dev/v1beta1\nkind: TriggerBinding\nmetadata:\nname: ww-pipeline-binding\nnamespace: ww-pipeline\nspec:\nparams:\n- name: namespace\nvalue: $(body.involvedObject.namespace)\n- name: name\nvalue: $(body.involvedObject.name)\n- name: message\nvalue: $(body.message)\nThe template has the same parameters as the Pipeline resources:
---\napiVersion: triggers.tekton.dev/v1beta1\nkind: TriggerTemplate\nmetadata:\nname: ww-pipeline-template\nnamespace: ww-pipeline\nspec:\nparams:\n- name: namespace\ndefault: \"Unknown\"\n- name: name\ndefault: \"Unknown\"\n- name: message\ndefault: \"no message\"\nresourcetemplates:\n- apiVersion: tekton.dev/v1beta1\nkind: PipelineRun\nmetadata:\ngenerateName: hello-goodbye-run-\nspec:\npipelineRef:\nname: hello-goodbye\nparams:\n- name: name\nvalue: $(tt.params.name)\n- name: namespace\nvalue: $(tt.params.namespace)\n- name: message\nvalue: $(tt.params.message)\nTo access all required resources, we need an extra service account:
---\napiVersion: v1\nkind: ServiceAccount\nmetadata:\nname: tekton-ww-pipeline-robot\nnamespace: ww-pipeline\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: RoleBinding\nmetadata:\nname: triggers-example-eventlistener-binding\nnamespace: ww-pipeline\nsubjects:\n- kind: ServiceAccount\nname: tekton-ww-pipeline-robot\nnamespace: ww-pipeline\nroleRef:\napiGroup: rbac.authorization.k8s.io\nkind: ClusterRole\nname: tekton-triggers-eventlistener-roles\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRoleBinding\nmetadata:\nname: triggers-example-eventlistener-clusterbinding\nsubjects:\n- kind: ServiceAccount\nname: tekton-ww-pipeline-robot\nnamespace: ww-pipeline\nroleRef:\napiGroup: rbac.authorization.k8s.io\nkind: ClusterRole\nname: tekton-triggers-eventlistener-clusterroles\nWith this ServiceAccount, we can create the EventListener using the TriggerBinding and TriggerTemplate:
---\napiVersion: triggers.tekton.dev/v1beta1\nkind: EventListener\nmetadata:\nname: ww-pipeline-listener\nnamespace: ww-pipeline\nspec:\nserviceAccountName: tekton-ww-pipeline-robot\ntriggers:\n- name: ww-pipeline-trigger\nbindings:\n- ref: ww-pipeline-binding\ntemplate:\nref: ww-pipeline-template\nAt this point, we should have a Service for our EventListener.
\u276f kubectl get service -n ww-pipeline\nNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE\nel-ww-pipeline-listener ClusterIP 10.96.250.23 <none> 8080/TCP,9000/TCP 3d\nIn this case, we are using Tekton in the same cluster, so we can use an internal address to access the EventListener service. If they are not in the same cluster, exposing the service may be required through an ingress or a service mesh.
---\napiVersion: notification.toolkit.fluxcd.io/v1beta1\nkind: Provider\nmetadata:\nname: tekton-promotion\nnamespace: hello-podinfo\nspec:\ntype: generic\naddress: http://el-ww-pipeline-listener.ww-pipeline:8080/\nWe can configure an Alert to use the tekton-promotion provider. For example, an Alert for the podinfo-pipeline in the flux-system namespace:
---\napiVersion: notification.toolkit.fluxcd.io/v1beta1\nkind: Alert\nmetadata:\nname: tekton-promotion-podinfo\nnamespace: hello-podinfo\nspec:\neventSeverity: info\neventSources:\n- kind: Pipeline\nname: hello-podinfo\nnamespace: flux-system\nproviderRef:\nname: tekton-promotion\nWarning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
Pipelines allow you to configure automatic promotions of applications through a consecutive set of environments, e.g. from dev to staging to production. The environments are defined in the Pipeline resource itself so that each pipeline governs a single application and all the environments to which it is deployed.
Info
At the moment only applications defined as Flux HelmReleases are supported in automatic promotions.
An example of a pull request for an application promotion
The Getting Started Guide describes how to create a basic pipeline for an application so you can visualize its deployments across a series of environments. You may also configure a pipeline in order to promote applications across a series of environments. There are currently two supported strategies for application promotions:
Before configuring any of the above promotion strategies, you need to setup notifications from all your environments so that whenever a new version gets deployed, the promotion webhook component of the pipeline controller is notified and takes an action based on the pipeline definition. The rest of this guide describes the configuration needed to setup application promotion via pipelines.
"},{"location":"pipelines/promoting-applications/#expose-the-promotion-webhook","title":"Expose the promotion webhook","text":"Applications deployed in leaf clusters use the Flux notification controller running on each leaf cluster, to notify the management cluster of a successful promotion. This requires network connectivity to be established between the leaf cluster and the management cluster.
The component responsible for listening to incoming notifications from leaf clusters is the pipeline controller. It hosts a webhook service that needs to be exposed via an ingress resource to make it available for external calls. Exposing the webhook service is done via the Weave GitOps Enterprise Helm chart values and the configuration used depends on your environment. The example below shows the configuration for NGINX ingress controller and needs to be adjusted if another ingress controller is used:
spec:\nvalues:\nenablePipelines: true\npipeline-controller:\npromotion:\ningress:\nenabled: true\nclassName: nginx\nannotations:\ncert-manager.io/cluster-issuer: letsencrypt\nhosts:\n- host: promotions.example.org\npaths:\n- path: /?(.*)\npathType: ImplementationSpecific\ntls:\n- secretName: promotions-tls\nhosts:\n- promotions.example.org\nYou will need the externally reachable URL of this service later on in this guide.
"},{"location":"pipelines/promoting-applications/#setup-notifications-from-leaf-clusters","title":"Setup notifications from leaf clusters","text":"Once the webhook service is exposed over HTTP/S, you need to create alert/provider resources to send notifications to it from leaf clusters. These notifications represent successful promotions for applications running on the leaf clusters.
Successful promotion events are triggered by Flux's notification controller. You create a Provider pointing to the promotion webhook exposed earlier and an Alert targeting the app's HelmRelease:
---\napiVersion: notification.toolkit.fluxcd.io/v1beta1\nkind: Provider\nmetadata:\nname: promotion-my-app\nspec:\naddress: \"https://promotions.example.org/promotion/pipeline-01/my-app/dev\"\ntype: generic-hmac\nsecretRef:\nname: hmac-secret\nIn the example above, the generic-hmac Provider is used to ensure notifications originate from authenticated sources. The referenced Secret, should include a token field which holds the HMAC key. The same HMAC key must be specified in the Secret referenced by the .spec.promotion.strategy.secretRef.name field, so that the pipeline controller can verify any incoming notifications. For more information on the generic-hmac Provider, please refer to the notification controller docs.
Note that by default, the promotion webhook endpoint is exposed at /promotion as shown in the example above. However you may use rewrite rules in your ingress configuration to omit it, if desired. For example, if using NGINX ingress controller, you may use the following annotation:
annotations:\nnginx.ingress.kubernetes.io/rewrite-target: /promotion/$1\nhttps://promotions.example.org/pipeline-01/my-app/dev. Tip
You may also use the generic webhook provider type that supports HMAC verification to ensure incoming notifications originate from authenticated sources.
The address field's URL path is comprised of 3 components again:
Weave GitOps Enterprise can then parse the incoming URL path to identify the pipeline resource and look up the next environment for the defined promotion action.
An example Alert might look like this:
---\napiVersion: notification.toolkit.fluxcd.io/v1beta1\nkind: Alert\nspec:\neventSeverity: info\neventSources:\n- kind: HelmRelease\nname: my-app\nexclusionList:\n- .*upgrade.*has.*started\n- .*is.*not.*ready\n- ^Dependencies.*\nproviderRef:\nname: promotion-my-app\nTip
Be sure to create the Provider/Alert tuple on each of the leaf clusters targeted by a pipeline.
Now as soon as the HelmRelease on the first environment defined in the pipeline is bumped (e.g. by Flux discovering a new version in the Helm repository), an event is sent to the promotion webhook which will determine the next action based on the pipeline definition and chosen strategy. The rest of this guide describes how to setup up any of the available strategies depending on your requirements.
Danger
Creating pull requests requires a personal access token with write access to your git repo. If the secret containing the token is compromised (and you could assume it as a likely scenario), it could in principle allow someone to delete your production applications.
Please make sure you understand the Security section below before taking the steps to enable automated pull requests.
This section covers adding a promotion by pull request (PR) strategy, so that whenever the application defined in a pipeline is upgraded in one of the pipeline's environments, a PR is created that updates the manifest file setting the application version in the next environment.
The dynamic nature of GitOps deployments requires you to assist Weave GitOps a little with information on which repository hosts the manifest files, how to authenticate with the repository and the Git provider API, and which file hosts the version definition for each environment.
"},{"location":"pipelines/promoting-applications/#security","title":"Security","text":""},{"location":"pipelines/promoting-applications/#environments-and-repositories","title":"Environments and Repositories","text":"Assign permissions at the namespace level where possible. Use RoleBindings as opposed to ClusterRoleBindings to give users rights only within a specific namespace.
Avoid providing wildcard permissions when possible, especially to all resources. As Kubernetes is an extensible system, providing wildcard access gives rights not just to all object types that currently exist in the cluster, but also to all object types which are created in the future.
It is also important to note that list and watch access also effectively allow users to read Secret contents.
"},{"location":"pipelines/promoting-applications/#policy","title":"Policy","text":"By following the guidelines above, you can have a safe initial configuration. However, given there are no deny semantics in RBAC, you need to guard future changes.
An RBAC Role or ClusterRole contains rules that represent a set of permissions. Permissions are purely additive (there are no \"deny\" rules).
You should ensure that attempts to break this contract are blocked and detected. You could achieve it by using Weave GitOps' Policy capabilities. The Policy Agent acts in two complementary modes: - Admission Controller protects from any attempt to create non-compliant RBAC resources that would end granting access to the secret. - Audit helps you identify already existing resources that are out of compliance. For example, roles created before policy agent was introduced as admission controller.
Once you have enabled Policy, the Policy Library gives you a set of good practices policies that will help you keep pipeline secrets secure according to the previous RBAC recommendations. Deploy them as Kustomization based on the following example:
Tip
In case you don't have access to the Policy Library, work with your Weaveworks Technical Account Manager (TAM) or Weaveworks Customer Reliability Engineer (CRE) to help with this step.
apiVersion: source.toolkit.fluxcd.io/v1\nkind: GitRepository\nmetadata:\nname: policy-library\nnamespace: flux-system\nspec:\ninterval: 10m0s\nurl: https://github.com/weaveworks/policy-library.git\nsecretRef:\nname: policy-library-github-credentials\n---\napiVersion: kustomize.toolkit.fluxcd.io/v1\nkind: Kustomization\nmetadata:\nname: rbac-secrets-good-practices\nnamespace: flux-system\nspec:\ninterval: 1m0s\nsourceRef:\nkind: GitRepository\nname: policy-library\npath: ./goodpractices/kubernetes/rbac/secrets\nprune: true\nPolicies typically allow exclusions, to accommodate privileged workloads like Flux. You can manage them via PolicyConfig. For example, in order to allow Flux you could use the following PolicyConfig:
apiVersion: pac.weave.works/v2beta2\nkind: PolicyConfig\nmetadata:\nname: allow-flux\nspec:\nmatch:\napps:\n- kind: Kustomization\nname: flux-system\nnamespace: flux-system\nconfig:\nweave.templates.rbac-prohibit-wildcards-policyrule-resources:\nparameters:\nexclude_label_key: \"app.kubernetes.io/part-of\"\nexclude_label_value: \"flux\"\nweave.templates.rbac-prohibit-wildcards-policyrule-verbs:\nparameters:\nexclude_label_key: \"app.kubernetes.io/part-of\"\nexclude_label_value: \"flux\"\nweave.policies.rbac-prohibit-list-secrets:\nparameters:\nexclude_label_key: \"app.kubernetes.io/part-of\"\nexclude_label_value: \"flux\"\nweave.policies.rbac-prohibit-watch-secrets:\nparameters:\nexclude_label_key: \"app.kubernetes.io/part-of\"\nexclude_label_value: \"flux\"\nweave.policies.rbac-prohibit-wildcard-secrets:\nparameters:\nexclude_label_key: \"app.kubernetes.io/part-of\"\nexclude_label_value: \"flux\"\nRemind not allowing users to create RBAC resources without compliance checks. Otherwise, they could create RBAC resources that could escape this runtime control.
In addition to guarding against privilege escalation via RBAC, you should guard against privilege escalation through workloads:
Permission to create workloads (either Pods, or workload resources that manage Pods) in a namespace implicitly grants access to many other resources in that namespace, such as Secrets, ConfigMaps, and PersistentVolumes that can be mounted in Pods
You could do that by creating pipeline namespaces to hold the Pipeline and its Secret, without permission to run workloads. You could enforce the latter one by using the Policy Containers Should Not Run In Namespace from the Policy Library and PolicyConfig as follows:
Tip
Update updates when onboarding a new pipeline. Consider using Weave Gitops self-service capabilities GitOps Templates or GitOpsSets to help you with the task.
apiVersion: pac.weave.works/v2beta2\nkind: PolicyConfig\nmetadata:\nname: reject-workloads-pipeline-namespace\nspec:\nmatch:\nnamespaces:\n- podinfo\nconfig:\nweave.policies.containers-should-not-run-in-namespace:\nparameters:\ncustom_namespace: \"podinfo\"\nTo enable the Pipeline Controller to read the secret, we need to grant access via RBAC. The promotion credentials secret needs to be in the same namespace as the Pipeline resource on the management cluster. You should create a RoleBinding for the Pipeline Controller ServiceAccount in the pipeline namespace. For a pipeline in namespace podinfo, it would look like the following:
---\napiVersion: rbac.authorization.k8s.io/v1\nkind: Role\nmetadata:\nname: read-app-promotion-credentials\nnamespace: podinfo # change for the pipeline namespace\nrules:\n- apiGroups:\n- \"\"\nresourceNames:\n- \"app-promotion-credentials\" # change for the secret name holding the pull requests secret\nresources:\n- \"secrets\"\nverbs:\n- \"get\"\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: RoleBinding\nmetadata:\nname: pipeline-controller-read-app-promotion-credentials\nnamespace: podinfo\nroleRef:\napiGroup: rbac.authorization.k8s.io\nkind: Role\nname: read-app-promotion-credentials\nsubjects:\n- kind: ServiceAccount\nname: chart-pipeline-controller # change in case pipeline controller service account has a different name in your context\nnamespace: flux-system\nUse pipeline promotions security to verify that your environments meets the security context described earlier.
Once deployed you could see how the different resources are being rejected. See those rejections in the Violations UI:
In addition, verify that the Pipeline controller can only get the secret by the following tests:
List access is denied:
$ kubectl get secret -n podinfo --as=system:serviceaccount:flux-system:chart-pipeline-controller\n\nError from server (Forbidden): secrets is forbidden: User \"system:serviceaccount:flux-system:chart-pipeline-controller\" cannot list resource \"secrets\" in API group \"\" in the namespace \"podinfo\"\nGet access is allowed:
$ kubectl get secret -n podinfo --as=system:serviceaccount:flux-system:chart-pipeline-controller app-promotion-credentials\n\nNAME TYPE DATA AGE\napp-promotion-credentials Opaque 1 21m\nFor example, if the case of GitHub, use fine-grained tokens to only allow access to the single repo that your configuration manifests exist.
For example, using github and fine-grained tokens you could do so.
The discovery of the version field is done using deterministic markers in a YAML manifest file. An example HelmRelease manifest with such a marker looks like this:
---\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nspec:\nchart:\nspec:\nversion: 0.13.7 # {\"$promotion\": \"pipeline-01:my-app:prod\"}\nThe value of the $promotion field in the comment is comprised of 3 components separated by colons:
Weave GitOps Enterprise will look for this marker whenever it receives an event from the respective HelmRelease of one of the leaf clusters and patch the file with the version denoted in the event (see the section above for instructions on setting up notification events from leaf clusters). Finally, it will create a Git provider PR to update the version of the application for the next environment in the pipeline.
"},{"location":"pipelines/promoting-applications/#supported-git-providers","title":"Supported Git Providers","text":"The following Git providers are currently support by this promotion strategy:
Select your Git provider via .spec.promotion.strategy.pull-request.type. For example, for gitlab it would look similar to:
promotion:\nstrategy:\npull-request:\ntype: gitlab\nurl: \"https://gitlab.com/weaveworks/<my-awesome-project.git>\"\nbaseBranch: main\nsecretRef:\nname: gitlab-promotion-credentials\nMore info in the spec.
"},{"location":"pipelines/promoting-applications/#credentials-secret","title":"Credentials Secret","text":"In the journey of creating a pull request, there are different secrets involved:
Create a Kubernetes secret with the previous data.
Expand to see example# example to use git over https with basic auth and pat\n$ kubectl create secret generic promotion-credentials \\\n--namespace=pipeline-01 \\\n--from-literal=\"username=<bot account name>\" \\\n--from-literal=\"password=<token value>\" \\\n--from-literal=\"token=<token value>\" \\\n--from-literal=\"hmac-key=<hmac-key value>\"\n---\napiVersion: v1\nkind: Secret\nmetadata:\nname: promotion-credentials\nnamespace: pipeline-01\ndata:\nusername: ZXhhbXBsZQ==\npassword: ZXhhbXBsZS1wYXNzd29yZA==\ntoken: Z2hwX01IL3RsTFpXTXZMY0FxVWRYY1ZGL0lGbzh0WDdHNjdsZmRxWQ==\nhmac-key: OEIzMTNBNjQ0REU0OEVGODgxMTJCQ0VFNTQ3NkE=\ntype: Opaque\nTip
The field .spec.promotion.strategy.pull-request defines details about the Git repository used for promoting the given app. Set the secretRef.name field to the name of the Secret created in the previous step and the url and branch fields to the Git repository's HTTPS URL and optionally a specific branch (if the branch is not set, it defaults to main). If using the generic-hmac Provider from leaf clusters, also set the .spec.promotion.strategy.secretRef.name to the name of the Secret created previously.
More info in the spec
"},{"location":"pipelines/promoting-applications/#notification","title":"Notification","text":"This section explains how to configure pipelines to work with external CI systems that are responsible for application promotions.
This strategy uses the notification controller running on the management cluster, to forward any notifications received by the promotion webhook, from leaf clusters to external CI systems. This requires to patch the Flux manifests of the management cluster, in order to allow objects of type Pipeline to be used as event sources. An example of a patch applied to enable this is shown below:
---\napiVersion: kustomize.config.k8s.io/v1beta1\nkind: Kustomization\nresources:\n- gotk-components.yaml\n- gotk-sync.yaml\npatches:\n- patch: |\n- op: add\npath: /spec/versions/0/schema/openAPIV3Schema/properties/spec/properties/eventSources/items/properties/kind/enum/-\nvalue: Pipeline\ntarget:\nkind: CustomResourceDefinition\nname: alerts.notification.toolkit.fluxcd.io\nYou can now create Provider/Alert resources on the management cluster to forward notifications to external systems. For example, the Provider resource shown below is used to invoke a GitHub Actions workflow on a repository:
---\napiVersion: notification.toolkit.fluxcd.io/v1beta1\nkind: Provider\nmetadata:\nname: promotion-my-app-via-github-actions\nspec:\ntype: githubdispatch\naddress: https://github.com/my-org/my-app-repo\nsecretRef:\nname: github-credentials\nTo use this Provider, add an Alert that uses the pipeline resource defined on the management cluster as an event source. An example of such an Alert is shown below:
---\napiVersion: notification.toolkit.fluxcd.io/v1beta1\nkind: Alert\nmetadata:\nname: promotion-my-app-via-github-actions\nspec:\neventSeverity: info\neventSources:\n- kind: Pipeline\nname: my-app\nnamespace: my-app-ns\nproviderRef:\nname: promotion-my-app-via-github-actions\nThe notification controller running on the management cluster is now configured to forward any promotion notifications received from leaf clusters. To actually use this strategy from a pipeline, set the promotion field as shown below:
---\napiVersion: pipelines.weave.works/v1alpha1\nkind: Pipeline\nmetadata:\nname: my-app\nnamespace: my-app-ns\nspec:\npromotion:\nnotification: {}\nPromotion notifications from leaf clusters should now be forwarded via the notification controller running on the management cluster and should include information about the version of the application being promoted.
"},{"location":"pipelines/promoting-applications/#manual-promotion","title":"Manual promotion","text":"The supported strategies mentioned above, do not require any user interaction when handling promotions. However, there is often a need for a human operator to manually approve a promotion to the next environment. To achieve that, set the spec.promotion.manual key to true.
apiVersion: pipelines.weave.works/v1alpha1\nkind: Pipeline\nmetadata:\nname: my-app\nnamespace: my-app-ns\nspec:\npromotion:\nmanual: true\nstrategy:\npull-request:\ntype: github\nurl: https://github.com/my-org/my-app-repo\nbaseBranch: main\nsecretRef:\nname: promotion-credentials\nWhen this key is set and a promotion is detected, Weave GitOps will prompt the user to manually promote the application to the next environment, via the use of a button shown under the next environment.
Manual promotion of an application"},{"location":"pipelines/promoting-applications/#configuration","title":"Configuration","text":""},{"location":"pipelines/promoting-applications/#retry-logic","title":"Retry Logic","text":"
By default if a promotion fails, an exponential back-off retry happens and returns with an error only after three retries.
Through Helm values, the retry logic is configurable.
# values.yaml\npromotion:\nretry:\n# Initial delay between retries.\ndelay: 2\n# Maximum delay between retries.\nmaxDelay: 20\n# Number of attempts.\nthreshold: 3\nThe promotion happens through an HTTP endpoint call, that endpoint may has connection timeout limits, that's why the maxDelay option is there. If the calculated delay would exceed this value, it will use that as delay. For example if the delay values would be [2, 4, 8, 16, 32, 64], but maxDelay is set to 15, the list will be [2, 4, 8, 15, 15, 15]. With this option, the promotion will be retried on failure, but the sum of delay values will be only 59 seconds instead of 126 seconds.
The promotion endpoint can be exposed to the internet (for example github actions), to mitigate DoS attacks, the endpoint has rate limits. By default it's 20 requests per 30 seconds.
Rate limiting can be configured through Helm values:
# values.yaml\npromotion:\nrateLimit:\n# Number of requests allowed in set interval.\nvalue: 20\ninterval: 30\nimport TierLabel from \"../../../_components/TierLabel\";
"},{"location":"pipelines/spec/v1alpha1/pipeline/#pipeline-enterprise","title":"Pipeline ENTERPRISE","text":"The Pipeline API defines a resource for continuous delivery pipelines.
An example of a fully defined pipeline that creates pull requests for application promotions is shown below.
apiVersion: pipelines.weave.works/v1alpha1\nkind: Pipeline\nmetadata:\nname: podinfo-02\nnamespace: flux-system\nspec:\nappRef:\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nname: podinfo\nenvironments:\n- name: dev\ntargets:\n- namespace: podinfo-02-dev\nclusterRef:\nkind: GitopsCluster\nname: dev\nnamespace: flux-system\n- name: test\ntargets:\n- namespace: podinfo-02-qa\nclusterRef:\nkind: GitopsCluster\nname: dev\nnamespace: flux-system\n- namespace: podinfo-02-perf\nclusterRef:\nkind: GitopsCluster\nname: dev\nnamespace: flux-system\n- name: prod\ntargets:\n- namespace: podinfo-02-prod\nclusterRef:\nkind: GitopsCluster\nname: prod\nnamespace: flux-system\npromotion:\nstrategy:\npull-request:\ntype: github\nurl: https://github.com/my-org/my-app-repo\nbaseBranch: main\nsecretRef:\nname: github-credentials\nThe documentation for version v1alpha1 of a Pipeline resource is found next.
// Pipeline is the Schema for the pipelines API\ntype Pipeline struct {\nmetav1.TypeMeta `json:\",inline\"`\nmetav1.ObjectMeta `json:\"metadata,omitempty\"`\n\nSpec PipelineSpec `json:\"spec,omitempty\"`\n// +kubebuilder:default={\"observedGeneration\":-1}\nStatus PipelineStatus `json:\"status,omitempty\"`\n}\n\ntype PipelineSpec struct {\n// Environments is a list of environments to which the pipeline's application is supposed to be deployed.\n// +required\nEnvironments []Environment `json:\"environments\"`\n// AppRef denotes the name and type of the application that's governed by the pipeline.\n// +required\nAppRef LocalAppReference `json:\"appRef\"`\n// Promotion defines details about how promotions are carried out between the environments\n// of this pipeline.\n// +optional\nPromotion *Promotion `json:\"promotion,omitempty\"`\n}\n\ntype Environment struct {\n// Name defines the name of this environment. This is commonly something such as \"dev\" or \"prod\".\n// +required\nName string `json:\"name\"`\n// Targets is a list of targets that are part of this environment. Each environment should have\n// at least one target.\n// +required\nTargets []Target `json:\"targets\"`\n// Promotion defines details about how the promotion is done on this environment.\n// +optional\nPromotion *Promotion `json:\"promotion,omitempty\"`\n}\n\ntype Target struct {\n// Namespace denotes the namespace of this target on the referenced cluster. This is where\n// the app pointed to by the environment's `appRef` is searched.\n// +required\nNamespace string `json:\"namespace\"`\n// ClusterRef points to the cluster that's targeted by this target. If this field is not set, then the target is assumed\n// to point to a Namespace on the cluster that the Pipeline resources resides on (i.e. a local target).\n// +optional\nClusterRef *CrossNamespaceClusterReference `json:\"clusterRef,omitempty\"`\n}\n\n// Promotion define promotion configuration for the pipeline.\ntype Promotion struct {\n// Manual option to allow promotion between to require manual approval before proceeding.\n// +optional\nManual bool `json:\"manual,omitempty\"`\n// Strategy defines which strategy the promotion should use.\nStrategy Strategy `json:\"strategy\"`\n}\n\n// Strategy defines all the available promotion strategies. All of the fields in here are mutually exclusive, i.e. you can only select one\n// promotion strategy per Pipeline. Failure to do so will result in undefined behaviour.\ntype Strategy struct {\n// PullRequest defines a promotion through a Pull Request.\n// +optional\nPullRequest *PullRequestPromotion `json:\"pull-request,omitempty\"`\n// Notification defines a promotion where an event is emitted through Flux's notification-controller each time an app is to be promoted.\n// +optional\nNotification *NotificationPromotion `json:\"notification,omitempty\"`\n// SecrefRef reference the secret that contains a 'hmac-key' field with HMAC key used to authenticate webhook calls.\n// +optional\nSecretRef *meta.LocalObjectReference `json:\"secretRef,omitempty\"`\n}\ntype GitProviderType string\n\nconst (\nGithub GitProviderType = \"github\"\nGitlab GitProviderType = \"gitlab\"\nBitBucketServer GitProviderType = \"bitbucket-server\"\n)\n\ntype PullRequestPromotion struct {\n// Indicates the git provider type to manage pull requests.\n// +required\n// +kubebuilder:validation:Enum=github;gitlab;bitbucket-server\nType GitProviderType `json:\"type\"`\n// The git repository HTTPS URL used to patch the manifests for promotion.\n// +required\nURL string `json:\"url\"`\n// The branch to checkout after cloning. Note: This is just the base\n// branch that will eventually receive the PR changes upon merge and does\n// not denote the branch used to create a PR from. The latter is generated\n// automatically and cannot be provided.\n// +required\nBaseBranch string `json:\"baseBranch\"`\n// SecretRef specifies the Secret containing authentication credentials for\n// the git repository and for the Git provider API.\n// For HTTPS repositories the Secret must contain 'username' and 'password'\n// fields.\n// For Git Provider API to manage pull requests, it must contain a 'token' field.\n// +required\nSecretRef meta.LocalObjectReference `json:\"secretRef\"`\n}\n\ntype NotificationPromotion struct{}\n// LocalAppReference is used together with a Target to find a single instance of an application on a certain cluster.\ntype LocalAppReference struct {\n// API version of the referent.\n// +required\nAPIVersion string `json:\"apiVersion\"`\n\n// Kind of the referent.\n// +required\nKind string `json:\"kind\"`\n\n// Name of the referent.\n// +required\nName string `json:\"name\"`\n}\n\n// CrossNamespaceClusterReference contains enough information to let you locate the\n// typed Kubernetes resource object at cluster level.\ntype CrossNamespaceClusterReference struct {\n// API version of the referent.\n// +optional\nAPIVersion string `json:\"apiVersion,omitempty\"`\n\n// Kind of the referent.\n// +required\nKind string `json:\"kind\"`\n\n// Name of the referent.\n// +required\nName string `json:\"name\"`\n\n// Namespace of the referent, defaults to the namespace of the Kubernetes resource object that contains the reference.\n// +optional\nNamespace string `json:\"namespace,omitempty\"`\n}\ntype PipelineStatus struct {\n// ObservedGeneration is the last observed generation.\n// +optional\nObservedGeneration int64 `json:\"observedGeneration,omitempty\"`\n\n// Conditions holds the conditions for the Pipeline.\n// +optional\nConditions []metav1.Condition `json:\"conditions,omitempty\"`\n}\n// Reasons are provided as utility, and are not part of the declarative API.\nconst (\n// TargetClusterNotFoundReason signals a failure to locate a cluster resource on the management cluster.\nTargetClusterNotFoundReason string = \"TargetClusterNotFound\"\n// TargetClusterNotReadyReason signals that a cluster pointed to by a Pipeline is not ready.\nTargetClusterNotReadyReason string = \"TargetClusterNotReady\"\n// ReconciliationSucceededReason signals that a Pipeline has been successfully reconciled.\nReconciliationSucceededReason string = \"ReconciliationSucceeded\"\n)\nWeave Policy Engine helps users have continuous security and compliance checks across their software delivery pipeline. The engine utilizes policy-as-code to guarantee security, resilience, and coding standards across applications and infrastructure. The engine comes with 100+ policies covering numerous security and compliance benchmarks like SOC2, GDPR, PCI-DSS, HIPAA, Mitre Attack and more.
The policy engine provides the following functionality:
"},{"location":"policy/#admission-controller","title":"Admission Controller","text":"An out-of-the-box admission controller that monitors any changes happening to the clusters' deployments and resources, and prevents violating changes at deployment time from being deployed to clusters.
"},{"location":"policy/#audit","title":"Audit","text":"Daily scans of your clusters' deployments and resources, then report back any policy violations. The audit results can be published to different data analytics tools to provide compliance posture analysis of your clusters runtime.
"},{"location":"policy/#commitbuild-time-checks","title":"Commit/Build Time Checks","text":"Early feedback on policy violations at the commit or build time, by reporting policy violations right inside git or other CI tools. This helps developers and operators detect policy violations and fix them before they deploy their changes to the clusters.
"},{"location":"policy/authorization/","title":"Authorization ENTERPRISE","text":"This section provides a recommended way to configure RBAC in the context of policies. It is oriented to the journey that you expect your users to have.
"},{"location":"policy/authorization/#view-resources","title":"View Resources","text":"The policy journey in the UI involves several resources. We have the Policies that are used by the agent, the resulting Violations when the agent enforces those policies, and the PolicyConfigs that the user can configure to override policy parameters. The violations are essentially kubernetes events that contain the Validation object.
In order to view those resources, users would need to have read access to the policies, policysconfigs, and events resource.
An example of a configuration to achieve this purpose could be seen below with policies-reader role and developer-policies-reader cluster role binding, to allow a group developer to access all the policy-related resources.
apiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRole\nmetadata:\nname: policies-reader\nrules:\n- apiGroups: [\"pac.weave.works\"]\nresources: [\"policies\", \"policyconfigs\"]\nverbs: [\"get\", \"list\", \"watch\"]\n- apiGroups: [\"\"]\nresources: [\"events\"]\nverbs: [\"get\", \"watch\", \"list\"]\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRoleBinding\nmetadata:\nname: developer-policies-reader\nsubjects:\n- kind: Group\nname: developer\napiGroup: rbac.authorization.k8s.io\nroleRef:\nkind: ClusterRole\nname: policies-reader\napiGroup: rbac.authorization.k8s.io\nWeave GitOps Enterprise enables developers and operators to check policy violations early in their software development life cycle, specifically at commit and build time. Developers and operators can have Weave Policy Validator integrated in their CI tools to validate whether their code changes are violating any policies or not.
Weave GitOps Enterprise offer a policy engine image that can be used to perform commit/build time checks.The image can be found on Docker Hub under the name: weaveworks/weave-iac-validator:v1.1.
USAGE:\n app [global options] command [command options] [arguments...]\n\nVERSION:\n 0.0.1\n\nCOMMANDS:\n help, h Shows a list of commands or help for one command\n\nGLOBAL OPTIONS:\n --path value path to scan resources from\n --helm-values-file value path to resources helm values file\n --policies-path value path to policies kustomization directory\n --policies-helm-values-file value path to policies helm values file\n --git-repo-provider value git repository provider\n --git-repo-host value git repository host\n --git-repo-url value git repository url\n --git-repo-branch value git repository branch\n --git-repo-sha value git repository commit sha\n --git-repo-token value git repository toke\n --azure-project value azure project name\n --sast value save result as gitlab sast format\n --sarif value save result as sarif format\n --json value save result as json format\n --generate-git-report generate git report if supported (default: false)\n--remediate auto remediate resources if possible (default: false)\n--no-exit-error exit with no error (default: false)\n--help, -h show help (default: false)\n--version, -v print the version (default: false)\nPolicies can be a helm chart, kustomize directory or just plain kubernetes yaml files.
Example of policies kustomize directory
\u2514\u2500\u2500 policies\n \u251c\u2500\u2500 kustomization.yaml\n \u251c\u2500\u2500 minimum-replica-count.yaml\n \u251c\u2500\u2500 privileged-mode.yaml\n \u2514\u2500\u2500 privilege-escalation.yaml\n # kustomization.yaml\nkind: Kustomization\napiVersion: kustomize.config.k8s.io/v1beta1\nresources:\n- minimum-replica-count.yaml\n- privilege-escalation.yaml\n- privileged-mode.yaml\nWeave validator supports auto-remediation functionality which creates a pull request with suggested fixes to remediate the reported violations.
Supported in:
To enable it you need to provide --remediate flag and --git-repo-token.
The token must have the permission to create a pull request.
"},{"location":"policy/commit-time-checks/#usecase-github","title":"UseCase: Github","text":"See how to setup the Github Action
"},{"location":"policy/commit-time-checks/#usecase-gitlab","title":"UseCase: Gitlab","text":" weave:\nimage:\nname: weaveworks/weave-iac-validator:v1.1\nscript:\n- weave-validator --path <path to resources> --policies-path <path to policies>\n script:\n- weave-validator --path <path to resources> --policies-path <path to policies> --git-repo-token $GITLAB_TOKEN --remediate\n stages:\n- weave\n- sast\n\nweave:\nstage: weave\nimage:\nname: weaveworks/weave-iac-validator:v1.1\nscript:\n- weave-validator <path to resources> --policies-path <path to policies> --sast sast.json\nartifacts:\nwhen: on_failure\npaths:\n- sast.json\n\nupload_sast:\nstage: sast\nwhen: always\nscript:\n- echo \"creating sast report\"\nartifacts:\nreports:\nsast: sast.json\npipelines:\ndefault:\n- step:\nname: 'Weaveworks'\nimage: weaveworks/weave-iac-validator:v1.1\nscript:\n- weave-validator --path <path to resources> --policies-path <path to policies>\n script:\n- weave-validator --path <path to resources> --policies-path <path to policies> --git-repo-token $TOKEN --remediate\n script:\n- weave-validator --path <path to resources> --policies-path <path to policies> --git-repo-token $TOKEN -generate-git-report\njobs:\nweave:\ndocker:\n- image: weaveworks/weave-iac-validator:v1.1\nsteps:\n- checkout\n- run:\ncommand: weave-validator --path <path to resources> --policies-path <path to policies>\n - run:\ncommand: weave-validator --path <path to resources> --policies-path <path to policies> --git-repo-token ${GITHUB_TOKEN} --remediate\ntrigger:\n- <list of branches to trigger the pipeline on>\n\npool:\nvmImage: ubuntu-latest\n\ncontainer:\nimage: weaveworks/weave-iac-validator:v1.1-azure\n\nsteps:\n- script: weave-validator --path <path to resources> --policies-path <path to policies> --git-repo-token $(TOKEN)\nsteps:\n- script: weave-validator --path <path to resources> --policies-path <path to policies> --git-repo-token $(TOKEN) --remediate\nEnabling the Weave Policy Engine features in Weave GitOps is done by running the policy agent on the cluster. This section gives an overview of the policy ecosystem and the steps required for installing and running the policy agent on leaf clusters.
"},{"location":"policy/getting-started/#the-policy-ecosystem","title":"The Policy Ecosystem","text":"The policy ecosystem consists of several moving parts. The two primary components are the Policy Agent and the Policy CRs. The agent runs in several modes, and uses the Policy CRs to perform validations on different resources. The results of those validations can be written to different sinks.
There are two other optional components: the PolicySet, and the PolicyConfig. The PolicySet can be used to filter policies for a specific mode, while the PolicyConfig can be used to override policy parameters during the validation of a certain resource.
"},{"location":"policy/getting-started/#installation-pre-requisites","title":"Installation Pre-requisites","text":""},{"location":"policy/getting-started/#weave-gitops","title":"Weave GitOps","text":"You need to have a running instance of Weave GitOps with at least one CAPI provider installed to provision Kubernetes clusters. See Weave GitOps Installation page for more details about installing Weave GitOps.
"},{"location":"policy/getting-started/#policy-library","title":"Policy Library","text":"For the policy agent to work, it will need a source for the policies that it will enforce in the cluster. Enterprise customers should request access to fork our policy library into their local repositories. Our policy library includes an extensive list of policy CRs that cover a multitude of security and compliance benchmarks.
"},{"location":"policy/getting-started/#install-the-policy-agent","title":"Install the Policy Agent","text":"To install the policy agent on a leaf cluster, you should select the weave-policy-agent from the profiles dropdown in the Create Cluster page.
You should then configure the values.yaml to pull the policies from your repo into the cluster. This is done by configuring the policySource section. If your policy library repo is private, you will also need to reference the Secret that contains the repo credentials. This is usually the secret you created while bootstrapping Flux on the management cluster and is copied to your leaf cluster during creation.
policySource:\nenabled: true\nurl: ssh://git@github.com/weaveworks/policy-library # This should be the url of the forked repo\ntag: v1.0.0\npath: ./ # Could be a path to the policies dir or a kustomization.yaml file\nsecretRef: my-pat # the name of the secret containing the repo credentials\npolicySource:\nenabled: true\nsourceRef: # Specify the name for an existing GitSource reference\nkind: GitRepository\nname: policy-library\nnamespace: flux-system\nYou can find more about other policy profile configurations here.
"},{"location":"policy/getting-started/#policies-in-ui","title":"Policies in UI","text":"After the leaf cluster is provisioned and the profile is installed, you should now see the policies listed in the Policies tab in Weave GitOps UI.
Now you have a provisioned cluster with these policies enforced by the policy agent.
By default, the policy profile is set up to enforce policies at deployment time using admission controller, which results in blocking any deployment that violates the enforced policies.
"},{"location":"policy/getting-started/#prevent-violating-changes","title":"Prevent Violating Changes","text":"Now let's try to deploy a Kubernetes deployment that violates the Container Image Pull Policy which is one of the enforced policies. This policy is violated when the container's imagePullPolicy is not set to Always.
apiVersion: apps/v1\nkind: Deployment\nmetadata:\nname: nginx-deployment\nlabels:\napp: nginx\nspec:\nreplicas: 3\nselector:\nmatchLabels:\napp: nginx\ntemplate:\nmetadata:\nlabels:\napp: nginx\nspec:\ncontainers:\n- name: nginx\nimage: nginx:1.14.2\nimagePullPolicy: IfNotPresent\nports:\n- containerPort: 80\nOnce you apply it, the policy agent will deny this request and show a violation message, and accordingly the deployment will not be created.
"},{"location":"policy/getting-started/#violations-logs-in-ui","title":"Violations Logs in UI","text":"You can go to the Violations Log in Weave GitOps UI to view the policy violations of all the connected clusters, and dive into the details of each violation.
This view shows only the violations resulting from the admission mode by configuring the events sink.
Violations Log
Violations Log Details
"},{"location":"policy/policy-configuration/","title":"PolicyConfig ENTERPRISE","text":""},{"location":"policy/policy-configuration/#goal","title":"Goal","text":"Users sometimes need to enforce the same policy(s) with different configurations (parameters) for different targets (workspaces, namespaces, applications, or resources). The PolicyConfig CRD allows us to do that without duplicating policies by overriding policy parameters of multiple policies for a specific target.
The PolicyConfig CRD consists of two sections 1) match used to specify the target of this PolicyConfig and 2) config used to specify the policy parameters that will override the orginal policy parameters.
apiVersion: pac.weave.works/v2beta2\nkind: PolicyConfig # policy config resource kind\nmetadata:\nname: my-config # policy config name\nspec:\nmatch: # matches (targets of the policy config)\nworkspaces: # add one or more name workspaces\n- team-a\n- team-b\nconfig: # config for policies [one or more]\nweave.policies.containers-minimum-replica-count:\nparameters:\nreplica_count: 3\nEach PolicyConfig CR can target either workspaces, namespaces, applications or resources. Targeting the same target explicitly in multiple PolicyConfigs is not allowed, ie: you can't use the same namespace in several PolicyConfigs which target namespaces.
To target workspaces:
match:\nworkspaces:\n- team-a\n- team-b\nTo target namespaces:
match:\nnamespaces:\n- dev\n- prod\nTo target applications:
match:\napps: # add one or more apps [HelmRelease, Kustomization]\n- kind: HelmRelease\nname: my-app # app name\nnamespace: flux-system # app namespace [if empty will match in any namespace]\nTo target resources:
match:\nresources: # add one or more resources [Deployment, ReplicaSet, ..]\n- kind: Deployment\nname: my-deployment # resource name\nnamespace: default # resource namespace [if empty will match in any namespace]\nEach PolicyConfig can override the parameters of one or more policies:
config: # config for policies [one or more]\nweave.policies.containers-minimum-replica-count: # the id of the policy\nparameters:\nreplica_count: 3\nowner: owner-4\nweave.policies.containers-running-in-privileged-mode:\nparameters:\nprivilege: true\nWhile it's not possible to create PolicyConfigs that explicitly target the same targets, it can happen implicitly ex: by targeting a namespace in a PolicyConfig and targeting an application that exists in this namespace in another. Whenever targets overlap, the narrower the scope of the PolicyConfig, the more precedence it has. Accordingly in the previous example, the configuration of the PolicyConfig targeting the application will have precedence over the PolicyConfig targeting the namespace.
Those are the possible targets from lowest to highest precedence:
Note:
We have a Kustomization application app-a and deployment deployment-1 which is part of this application.
apiVersion: pac.weave.works/v2beta2\nkind: PolicyConfig\nmetadata:\nname: my-config-1\nspec:\nmatch:\nnamespaces:\n- flux-system\nconfig:\nweave.policies.containers-minimum-replica-count:\nparameters:\nreplica_count: 2\nowner: owner-1\n---\napiVersion: pac.weave.works/v2beta2\nkind: PolicyConfig\nmetadata:\nname: my-config-2\nspec:\nmatch:\napps:\n- kind: Kustomization\nname: app-a\nconfig:\nweave.policies.containers-minimum-replica-count:\nparameters:\nreplica_count: 3\n---\napiVersion: pac.weave.works/v2beta2\nkind: PolicyConfig\nmetadata:\nname: my-config-3\nspec:\nmatch:\napps:\n- kind: Kustomization\nname: app-a\nnamespace: flux-system\nconfig:\nweave.policies.containers-minimum-replica-count:\nparameters:\nreplica_count: 4\n---\napiVersion: pac.weave.works/v2beta2\nkind: PolicyConfig\nmetadata:\nname: my-config-4\nspec:\nmatch:\nresources:\n- kind: Deployment\nname: deployment-1\nconfig:\nweave.policies.containers-minimum-replica-count:\nparameters:\nreplica_count: 5\nowner: owner-4\n---\n\napiVersion: pac.weave.works/v2beta2\nkind: PolicyConfig\nmetadata:\nname: my-config-5\nspec:\nmatch:\nresources:\n- kind: Deployment\nname: deployment-1\nnamespace: flux-system\nconfig:\nweave.policies.containers-minimum-replica-count:\nparameters:\nreplica_count: 6\nIn the above example when you apply the 5 configurations...
Note
Deploying deployment-1 in another namespace other than flux-system won't be affected by this configuration
Final config values will be as follows:
config:\nweave.policies.containers-minimum-replica-count:\nparameters:\nreplica_count: 6 # from my-config-5\nowner: owner-4 # from my-config-4\nIn the above example when you apply my-config-1, my-config-2, my-config-3 and my-config-4
Final config values will be as follows:
config:\nweave.policies.containers-minimum-replica-count:\nparameters:\nreplica_count: 5 # from my-config-4\nowner: owner-4 # from my-config-4\nIn the previous example when you apply my-config-1, my-config-2 and my-config-3
Note
Deploying app-a in another namespace other than flux-system won't be affected by this configuration
Final config values will be the follows:
config:\nweave.policies.containers-minimum-replica-count:\nparameters:\nreplica_count: 4 # from my-config-3\nowner: owner-1 # from my-config-1\nIn the above example when you apply my-config-1 and my-config-2
Final config values will be as follows:
config:\nweave.policies.containers-minimum-replica-count:\nparameters:\nreplica_count: 3 # from my-config-2\nowner: owner-1 # from my-config-1\nIn the above example when you apply my-config-1
Final config values will be as follows:
config:\nweave.policies.containers-minimum-replica-count:\nparameters:\nreplica_count: 2 # from my-config-1\nowner: owner-1 # from my-config-1\nThis is an optional custom resource that is used to select a group of policies to work in specific modes.
In each mode, the agent will list all the PolicySets of this mode and check which policies match any of those policysets, then validate the resources against them.
If there are no PolicySets found for a certain mode, all policies will be applied during this mode.
Note: Tenant Policies is always active in the Admission mode, event if it is not selected in the admission policysets
Example
apiVersion: pac.weave.works/v2beta2\nkind: PolicySet\nmetadata:\nname: my-policy-set\nspec:\nmode: admission\nfilters:\nids:\n- weave.policies.containers-minimum-replica-count\ncategories:\n- security\nseverities:\n- high\n- medium\nstandards:\n- pci-dss\ntags:\n- tag-1\nPolicySets can be created for any of the three modes supported by the agent: admission, audit, and tfAdmission.
Policies can be grouped by their ids, categories, severities, standards and tags
The policy will be applied if any of the filters are matched.
"},{"location":"policy/policy-set/#migration-from-v2beta1-to-v2beta2","title":"Migration from v2beta1 to v2beta2","text":""},{"location":"policy/policy-set/#new-fields","title":"New fields","text":"Previously the agent was configured with which policysets to use in each mode. Now we removed this argument from the agent's configuration and add the mode to the Policyset itself.
"},{"location":"policy/policy-set/#example-of-the-agent-configuration-in-versions-older-than-v200","title":"Example of the agent configuration in versions older than v2.0.0","text":"# config.yaml\nadmission:\nenabled: true\npolicySet: admission-policy-set\nsinks:\nfilesystemSink:\nfileName: admission.txt\napiVersion: pac.weave.works/v2beta2\nkind: PolicySet\nmetadata:\nname: admission-policy-set\nspec:\nmode: admission\nfilters:\nids:\n- weave.policies.containers-minimum-replica-count\nThe Policy CRD is used to define policies which are then consumed and used by the agent to validate entities.
It uses OPA Rego Language to evaluate the entities.
"},{"location":"policy/policy/#policy-library","title":"Policy Library","text":"You should have a policy library repo set up which includes your policies resources as CRDs.
Info
Enterprise customers should have access to fork policy library repo into their local repositories.
"},{"location":"policy/policy/#tenant-policy","title":"Tenant Policy","text":"Tenant policies are special policies that are used by the Multi Tenancy feature in Weave GitOps Enterprise
Tenant policies have a special tag tenancy.
Starting from version v2.2.0, the policy agent will support mutating resources.
To enable mutating resources, policies must have field mutate set to true and the rego code should return the violating_key and the recommended_value in the violation response. The mutation webhook will use the violating_key and recommended_value to mutate the resource and return the new mutated resource.
Example
result = {\n \"issue_detected\": true,\n \"msg\": sprintf(\"Replica count must be greater than or equal to '%v'; found '%v'.\", [min_replica_count, replicas]),\n \"violating_key\": \"spec.replicas\",\n \"recommended_value\": min_replica_count\n}\nThe policy validation object is the result of validating an entity against a policy. It contains all the necessary information to give the user a clear idea on what caused this violation or compliance.
id: string # identifier for the violation\naccount_id: string # organization identifier\ncluster_id: string # cluster identifier\npolicy: object # contains related policy data\nentity: object # contains related resource data\nstatus: string # Violation or Compliance\nmessage: string # message that summarizes the policy validation\ntype: string # the mode that produced this object. one of: Admission, Audit, TFAdmission\ntrigger: string # what triggered the validation, create request or initial audit,..\ncreated_at: string # time that the validation occurred in\nCompatible with Policy Library versions:
Needs this migration steps to be compatible with the following versions:
Compatible with Policy Library versions:
Needs this migration steps to be compatible with the following versions:
While both v.0.4.0 and v1.0.0 are compatible with the agent. Only v1.1.0 includes the modification needed to make Controller Minimum Replica Count policy with with horizontalpodautoscalers
Weave policy profile provides policies to automate the enforcement of best practices and conventions. It ensures the compliance of workloads through the use of a policy agent that provides an admission controller webhook that stops violating resources from deploying to a cluster and runs a daily audit that reports violating resources already deployed.
The profile configuration contains two main sections policySource to configure the source for deploying policies and policy-agent to configure the policy agent.
policy-agent:\nfailurePolicy: Ignore\n\n# If you don't want to use cert-manager, set useCertManager to false and provide your own certs\nuseCertManager: true\ncertificate: \"\"\nkey: \"\"\ncaCertificate: \"\"\n\npersistence:\nenabled: false\n# claimStorage: 1Gi\n# sinkDir: /tmp\n# storageClassName: standard\n\nconfig:\naccountId: \"\"\nclusterId: \"\"\n\naudit:\n# Enable audit functionality\nenabled: false\n# sinks:\n# # Enable writing violations as K8s events\n# k8sEventsSink:\n# enabled: true\n\nadmission:\n# Enable admission functionality\nenabled: true\n# mutate: true # enable mutating violating resources\nsinks:\n# Enable writing violations as K8s events\nk8sEventsSink:\nenabled: true\n\n\npolicySource:\nenabled: false\n# url: ssh://git@github.com/weaveworks/policy-library\n# tag: v1.0.0\n# branch:\n# path: ./ # Could be a path to the policies dir or a kustomization.yaml file\n# secretRef: policy-library-auth # (Optional): Name of the K8s secret with private repo auth credentials\n# sourceRef: # Could specify a name for an existing GitSource reference instead of creating a new one\n# kind: GitRepository\n# name: policy-library\n# namespace: flux-system\nPolicies are provided in the profile as Custom Resources. The agent reads from the policies deployed on the cluster and runs them during each admission request or when auditing a resource.
Policies are hosted in a policy library which is usually a git repository. They are fetched in the profile through the use of kustomize.toolkit.fluxcd.io.Kustomization, that deploys the policies to the cluster.
By default all policies in the specified path would be deployed in order to specify which policies should be deployed in a library, a kustomize.config.k8s.io.Kustomization file should be defined in the repository.
apiVersion: kustomize.config.k8s.io/v1beta1\nkind: Kustomization\nresources: # specifies the path to each required policy\n- policies/ControllerContainerAllowingPrivilegeEscalation/policy.yaml\n- policies/ControllerContainerRunningAsRoot/policy.yaml\n- policies/ControllerReadOnlyFileSystem/policy.yaml\nThe profile then needs to be configured with the necessary config to be able to reach the repository that is acting as a policy library.
policySource:\nenabled: true\nurl: URL of the repo where your policies exist\ntag: tag name on the policies repo\npath: Path to the policies dir - or a kustomization.yaml that selects some policies - in the repo\nsecretRef (if the repo is private): Name of the K8s secret with private repo credentials (leave empty if the repo is public)\nThere is the option of referencing an existing policy library source instead of creating a new one.
policySource:\nenabled: true\nsourceRef:\nkind: Kind of the existing source\nname: Name of the policy library source\nnamespace: Namespace where the source exists\nThe config section is the single entry point for configuring the agent.
The agent needs the following parameters to be provided in the configuration yaml file:
The following optional parameters can also be provided:
This contains the admission module that enforces policies. It uses the controller-runtime Kubernetes package to register a callback that will be called when the agent receives an admission request. Once called, the agent will validate the received resource against the admission and tenant policies and k8s will use the result of this validation to either allow or reject the creation/update of said resource.
Works with policies of provider kubernetes
To enable admission control:
policy-agent:\nconfig:\nadmission:\nenabled: true\nEnabling admission controller requires certificates for secure communication with the webhook client and the admission server. The best way to achieve this is by installing cert manager and then configuring the profile as follows:
policy-agent:\nuseCertManager: true\nThe cert manager can also be installed by installing the cert manager profile while creating the cluster.
There is the option of providing previously generated certificates although it is not recommended and it is up to the user to manage it:
policy-agent:\ncertificate: \"---\" # admission server certificate\nkey: \"---\" # admission server private key\ncaCertificate: \"---\" # CA bundle to validate the webhook server, used by the client\nIf the agent webhook could not be reached or the request failed to complete, the corresponding request would be refused. To change that behavior and accepts the request in cases of failure, this needs to be set:
policy-agent:\nfailurePolicy: Ignore\nThe audit functionality provides a full scan of the cluster(s) and reports back policy violations. This usually is used for policy violations reporting, and compliance posture analysis against known benchmarks like PCI DSS, CIS, .etc.
Works with policies of provider kubernetes
To enable the audit functionality:
policy-agent:\nconfig:\naudit:\nenabled: true\ninterval: 24 # configuring the frequent of audit operations running in hours (default is 24 hours)\nThe audit will be performed when the agent starts and then again periodically at an interval of your choice in hours (default is 24 hours). The results of the audit will be published to the configured sink(s).
"},{"location":"policy/weave-policy-profile/#terraform-admission","title":"Terraform Admission","text":"This is a webhook used to validate terraform plans. It is mainly used by the TF-Controller to enforce policies on terraform plans
Works with policies of provider terraform
To enable the terraform admission control:
policy-agent:\nconfig:\ntfAdmission:\nenabled: true\nWhen validating a resource, a validation object is generated that contains information about the status of that validation and metadata about the resource and policy involved. These objects can be exported to be visible for users as a critical part of the audit flow, but can also be useful as logs for the admission scenario.
By default, the agent only writes policy validations that are violating a certain policy when performing an audit. To write compliance results as well, the following needs to be specified in the profile:
policy-agent:\nconfig:\naudit:\nwriteCompliance: true\nThe agent profile supports storing the validations in different sinks. Multiple sinks can be used at the same time:
Text fileKubernetes EventsNotification ControllerElasticsearchThe results will be dumped into a text file in the logs directory, in the agent container as a json string. It is important to note that this file will not be persisted and will be deleted upon pod restart, so generally this approach is not recommended for a production environment.
To enable writing to a text file in audit scenario:
policy-agent:\nconfig:\naudit:\nsinks:\nfileSystemSink:\nfileName: \"file.json\"\nTo enable writing to a text file in admission scenario:
policy-agent:\nconfig:\nadmission:\nsinks:\nfileSystemSink:\nfileName: \"file.json\"\nIt is possible to make the file persistent using the following configuration. This assumes that there is a PersistentVolume already configured on the cluster.
policy-agent:\npersistence:\nenabled: false # specifies whether to use persistence or not\nclaimStorage: 1Gi # claim size\nstorageClassName: standard # k8s StorageClass name\nThe results will be written as Kubernetes events. This means that they are accessible through the kubernetes API and can be consumed by custom exporters.
To enable writing Kubernetes events in audit scenario:
policy-agent:\nconfig:\naudit:\nsinks:\nk8sEventsSink:\nenabled: true\nTo enable writing Kubernetes events in admission scenario:
policy-agent:\nconfig:\nadmission:\nsinks:\nk8sEventsSink:\nenabled: true\nThis requires the cluster to be managed using flux. It makes use of the flux notification controller to send events to multiple sources, depending on the controller configuration. The agent writes the events to the controller and it proceeds to publish it to the configured listeners.
To enable writing to flux notification controller in audit scenario:
policy-agent:\nconfig:\naudit:\nsinks:\nfluxNotificationSink:\naddress: \"\"\nTo enable writing to flux notification controller in admission scenario:
policy-agent:\nconfig:\nadmission:\nsinks:\nfluxNotificationSink:\naddress: \"\"\nThe results of validating entities against policies will be written to an Elasticsearch index.
To enable writing to elasticsearch in audit scenario:
policy-agent:\nconfig:\naudit:\nsinks:\nelasticSink:\naddress: \"\"\nusername: \"\"\npassword: \"\"\nindexName: \"\"\ninsertionMode: \"upsert\"\nTo enable writing to elasticsearch in admission scenario:
policy-agent:\nconfig:\nadmission:\nsinks:\nelasticSink:\naddress: \"\"\nusername: \"\"\npassword: \"\"\nindexName: \"\"\ninsertionMode: \"insert\"\nWe support the following insertion modes:
To help you understand the state of progressive delivery updates to your applications, Weave GitOps Enterprise uses Flagger\u2014part of the Flux family of open source projects. WGE's Delivery view shows all of your deployed Canary objects and rollout progress.
By default, Flagger automatically promotes a new version of an application whenever it passes the defined checks of an analysis phase. However, you can also configure webhooks to enable manual approvals of rollout stages.
This guide shows you how to manually gate a progressive delivery promotion with Flagger by using the in-built load tester.
"},{"location":"progressive-delivery/flagger-manual-gating/#prerequisites","title":"Prerequisites","text":"You can configure Flagger to work with several types of hooks that will be called at given stages during a progressive delivery rollout. Some of these hooks allow you to manually gate whether a rollout proceeds at certain points: - Before scaling up a new deployment and canary analysis begins with confirm-rollout. - Before increasing traffic weight with confirm-traffic-increase. - Before promoting a new version after successful canary analysis with confirm-promotion.
Any URL can serve as a webhook target. It will approve if a 200 OK status code is returned, and halt if 403 Forbidden.
The webhook will receive a JSON payload that can be unmarshaled as CanaryWebhookPayload:
type CanaryWebhookPayload struct {\n// Name of the canary\nName string `json:\"name\"`\n\n// Namespace of the canary\nNamespace string `json:\"namespace\"`\n\n// Phase of the canary analysis\nPhase CanaryPhase `json:\"phase\"`\n\n// Metadata (key-value pairs) for this webhook\nMetadata map[string]string `json:\"metadata,omitempty\"`\n}\nThe Flagger documentation provides more information about webhooks.
"},{"location":"progressive-delivery/flagger-manual-gating/#use-flaggers-load-tester-to-manually-gate-a-promotion","title":"Use Flagger's Load Tester to Manually Gate a Promotion","text":"To enable manual approval of a promotion, configure the confirm-promotion webhook. This will call a particular gate provided through Flagger's load tester, and is an easy way to experiment using Flagger's included components.
Tip
We strongly recommend that you DO NOT USE the load tester for manual gating in a production environment. It lacks auth, so anyone with cluster access could open and close it. It also lacks storage, so all gates would close upon a restart. Instead, configure these webhooks for appropriate integration with a tool of your choice, such Jira, Slack, Jenkins, etc.
"},{"location":"progressive-delivery/flagger-manual-gating/#configure-the-confirm-promotion-webhook","title":"Configure theconfirm-promotion Webhook","text":"In your canary object, add the following in the analysis section:
analysis:\nwebhooks:\n- name: \"ask for confirmation\"\ntype: confirm-promotion\nurl: http://flagger-loadtester.test/gate/check\nThis gate is closed by default.
"},{"location":"progressive-delivery/flagger-manual-gating/#deploy-a-new-version-of-your-application","title":"Deploy a New Version of Your Application","text":"Trigger a Canary rollout by updating your target deployment/daemonset\u2014for example, by bumping the container image tag. A full list of ways to trigger a rollout is available here.
Weave GitOps Enterprise (WGE)'s Applications > Delivery view enables you to watch the progression of a canary:
"},{"location":"progressive-delivery/flagger-manual-gating/#wait-for-the-canary-analysis-to-complete","title":"Wait for the Canary Analysis to Complete","text":"Once the canary analysis has successfully completed, Flagger will call the confirm-promotion webhook and change status to WaitingPromotion:
To open the gate and confirm that you approve promotion of the new version of your application, exec into the load tester container:
$ kubectl -n test exec -it flagger-loadtester-xxxx-xxxx sh\n\n# to open\n> curl -d '{\"name\": \"app\",\"namespace\":\"test\"}' http://localhost:8080/gate/open\nFlagger will now promote the canary version to the primary and complete the progressive delivery rollout.
To manually close the gate again, issue this command:
> curl -d '{\"name\": \"app\",\"namespace\":\"test\"}' http://localhost:8080/gate/close\nReferences:
Built upon the core tenets of continuous integration and continuous delivery (CI/CD), progressive delivery involves gradually rolling out features to small groups of select users to balance performance with speed. Developers and DevOps teams use fine-grained controls to minimize the risks of pushing new features to the production environment. If the newly released feature proves to be stable and performant, it can then be released to all users.
Flagger is a progressive delivery operator for Kubernetes and part of the Flux family of open source projects. It reduces the risk of introducing new software versions and automates production releases to improve your time to delivery. Flagger implements deployment strategies\u2014canary releases, A/B testing, Blue/Green mirroring\u2014using a service mesh (App Mesh, Istio, Linkerd, Kuma, Open Service Mesh) or an ingress controller (Contour, Gloo, NGINX, Skipper, Traefik, APISIX) for traffic routing. For release analysis, Flagger can query Prometheus, InfluxDB, Datadog, New Relic, CloudWatch, Stackdriver, or Graphite. For alerting it uses Slack, MS Teams, Discord, and Rocket. Using Flux allows us to manage our cluster applications in a declarative way through changes in a Git repository.
Weave GitOps Enterprise integrates with Flagger in order to provide a view on progressive delivery deployments. This includes the ability to view all the resources that Flagger manages during its operation. The default ClusterRole gitops-canaries-reader includes the minimum permissions necessary for a user to be able to view canary object details, metric template object details and canary related events.
The WGE UI's Applications > Delivery view provides an \"at a glance\" view so that you can understand the status of your progressive delivery rollouts across a fleet of connected clusters. This removes the cognitive overhead of having to know which objects to query and where they are located. You can also drill down into each rollout to understand its status and configuration, and view near-to-realtime data on any summary or details page.
How to use WGE's progressive delivery offering: - if you don\u2019t have Flagger installed on any clusters, you'll receive an onboarding message about installing it - click on the delivery tab on the menu bar to retrieve a table view of canaries with key summary information regarding their location and state - click on a canary to see more detailed information about status, gates, and other elements - click on the events tab on the detail page to see the most recent Kubernetes events for that canary and learn more about deployment history - click on the yaml tab on the detail page to see the raw yaml of the canary - view objects from any cluster/namespace that you have the appropriate permissions for, and nothing else
Supported deployment strategies include:
Canary Release: the system gradually shifts traffic to a new version of an application and assesses performance\u2014either promoting the release or abandoning it, based on performance.
A/B Testing: uses HTTP headers or cookies to ensure users remain on the same version of an application during a canary analysis.
Blue/Green: Traffic is switched from the current application to a new version based on the success of testing.
Blue/Green with Traffic Mirroring: sends copies of incoming requests to the new version of an application. The user receives the response from the current application and the other is discarded. The new version is promoted only if metrics are healthy.
This guide uses Flux manifests to install Flagger and Linkerd, a CNCF project and service mesh for Kubernetes and beyond. We will walk you through a full end-to-end scenario where you will: - Install the Linkerd service mesh - Install Flagger - Deploy a sample application using a canary release strategy based on metrics provided through Linkerd's in-built Prometheus instance
"},{"location":"progressive-delivery/progressive-delivery-flagger-install/#prerequisites","title":"Prerequisites","text":"To install Linkerd we'll use a Kustomization file. It will allow us to specify the order and default namespace for the installed resources, and to generate Secrets from certificate files via the use of a secretGenerator.
To support mTLS connections between meshed pods, Linkerd requires a trust anchor certificate and an issuer certificate with its corresponding key. These certificates are automatically created via the linkerd install command. However, when using a Helm chart to install Linkerd, you must provide these certificates deliberately. The step CLI, listed above, allows us to generate these certificates.
To generate the trust anchor certificate, run:
step certificate create root.linkerd.cluster.local ca.crt ca.key \\\n--profile root-ca --no-password --insecure\nTo generate the issuer certificate, run:
step certificate create identity.linkerd.cluster.local issuer.crt issuer.key \\\n--profile intermediate-ca --not-after 8760h --no-password --insecure \\\n--ca ca.crt --ca-key ca.key\nAdd the ca.crt, issuer.crt, and issuer.key files to the cluster repository under a linkerd directory.
Let's add the three manifests for Linkerd components under the ./linkerd directory: - A Namespace resource to control where the components are installed - A HelmRepository resource to make the Linkerd Helm repo available on the cluster - A HelmRelease resource to install the latest version of Linkerd from the HelmRepository
---\napiVersion: v1\nkind: Namespace\nmetadata:\nname: linkerd\nlabels:\nconfig.linkerd.io/admission-webhooks: disabled\n---\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: HelmRepository\nmetadata:\nname: linkerd\nspec:\ninterval: 1h\nurl: https://helm.linkerd.io/stable\nNote: The value for the spec.values.identity.issuer.crtExpiry field below depends on the parameter value used during the creation of the issuer certificate. In this example, it should be set to one year from the certificate creation.
---\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: linkerd\nspec:\ninterval: 10m\nchart:\nspec:\nchart: linkerd2\nreconcileStrategy: ChartVersion\nsourceRef:\nkind: HelmRepository\nname: linkerd\ninstall:\ncrds: Create\nupgrade:\ncrds: CreateReplace\nvaluesFrom:\n- kind: Secret\nname: linkerd-certs\nvaluesKey: ca.crt\ntargetPath: identityTrustAnchorsPEM\n- kind: Secret\nname: linkerd-certs\nvaluesKey: issuer.crt\ntargetPath: identity.issuer.tls.crtPEM\n- kind: Secret\nname: linkerd-certs\nvaluesKey: issuer.key\ntargetPath: identity.issuer.tls.keyPEM\nvalues:\ninstallNamespace: false\nidentity:\nissuer:\ncrtExpiry: \"2023-07-18T20:00:00Z\" # Change this to match generated certificate expiry date\n---\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: linkerd-viz\nspec:\ninterval: 10m\ndependsOn:\n- name: linkerd\nchart:\nspec:\nchart: linkerd-viz\nreconcileStrategy: ChartVersion\nsourceRef:\nkind: HelmRepository\nname: linkerd\nNext, add the following manifests. The first file instructs Kustomize to patch any Secrets that are referenced in HelmRelease manifests. The second file is a Kustomization that references all the other linkerd resource files.
nameReference:\n- kind: Secret\nversion: v1\nfieldSpecs:\n- path: spec/valuesFrom/name\nkind: HelmRelease\n---\napiVersion: kustomize.config.k8s.io/v1beta1\nkind: Kustomization\nnamespace: linkerd\nconfigurations:\n- kustomizeconfig.yaml\nresources:\n- namespace.yaml\n- source.yaml\n- releases.yaml\nsecretGenerator:\n- name: linkerd-certs\nfiles:\n- ca.crt\n- issuer.crt\n- issuer.key\nNote: The secretGenerator generates Secrets from the files you've just created.
At this point the linkerd directory in your cluster repository should look like this:
> tree linkerd\nlinkerd\n\u251c\u2500\u2500 ca.crt\n\u251c\u2500\u2500 issuer.crt\n\u251c\u2500\u2500 issuer.key\n\u251c\u2500\u2500 kustomization.yaml\n\u251c\u2500\u2500 kustomizeconfig.yaml\n\u251c\u2500\u2500 namespace.yaml\n\u251c\u2500\u2500 releases.yaml\n\u2514\u2500\u2500 source.yaml\nOnce Flux reconciles this directory to the cluster, Linkerd should be installed.
Before proceeding to the next step, check that all the Linkerd pods have started successfully:
> kubectl get pods -n linkerd \nNAME READY STATUS RESTARTS AGE\nlinkerd-destination-66d5668b-4mw49 4/4 Running 0 10m\nlinkerd-identity-6b4658c74b-6nc97 2/2 Running 0 10m\nlinkerd-proxy-injector-6b76789cb4-8vqj4 2/2 Running 0 10m\n\n> kubectl get pods -n linkerd-viz \nNAME READY STATUS RESTARTS AGE\ngrafana-db56d7cb4-xlnn4 2/2 Running 0 10m\nmetrics-api-595c7b564-724ps 2/2 Running 0 10m\nprometheus-5d4dffff55-8fscd 2/2 Running 0 10m\ntap-6dcb89d487-5ns8n 2/2 Running 0 10m\ntap-injector-54895654bb-9xn7k 2/2 Running 0 10m\nweb-6b6f65dbc7-wltdg 2/2 Running 0 10m\nNote
Any new directories that you add to the cluster repository while following this guide must be included in a path that Flux reconciles.
"},{"location":"progressive-delivery/progressive-delivery-flagger-install/#installing-flagger-using-flux","title":"Installing Flagger Using Flux","text":"To install Flagger, you'll use a Kustomization file that will define the installation order and provide a default namespace for the installed resources.
Create a new flagger directory. Make sure to locate it under a repository path that Flux reconciles.
Now add under this directory the three resource manifests for Flagger: - A Namespace resource to control where the components are installed - A HelmRepository resource to make the Flagger Helm repo available on the cluster - A HelmRelease resource to install the latest version of Flagger and the load tester app (which generates synthetic traffic during the analysis phase), from that HelmRepository
---\napiVersion: v1\nkind: Namespace\nmetadata:\nname: flagger\n---\napiVersion: source.toolkit.fluxcd.io/v1beta2\nkind: HelmRepository\nmetadata:\nname: flagger\nspec:\ninterval: 1h\nurl: https://flagger.app\n---\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: flagger\nspec:\nreleaseName: flagger\ninstall:\ncrds: Create\nupgrade:\ncrds: CreateReplace\ninterval: 10m\nchart:\nspec:\nchart: flagger\nreconcileStrategy: ChartVersion\nsourceRef:\nkind: HelmRepository\nname: flagger\nvalues:\nmetricsServer: http://prometheus.linkerd-viz:9090\nmeshProvider: linkerd\n---\napiVersion: helm.toolkit.fluxcd.io/v2beta1\nkind: HelmRelease\nmetadata:\nname: loadtester\nspec:\ninterval: 10m\nchart:\nspec:\nchart: loadtester\nreconcileStrategy: ChartVersion\nsourceRef:\nkind: HelmRepository\nname: flagger\nNow add the following Kustomization file. It references all of the previous files that you've added:
Expand to see the Flagger Kustomization manifest flagger/kustomization.yaml---\napiVersion: kustomize.config.k8s.io/v1beta1\nkind: Kustomization\nnamespace: flagger\nresources:\n- namespace.yaml\n- source.yaml\n- releases.yaml\nThe flagger directory in the cluster repository should look like this:
> tree flagger\nflagger\n\u251c\u2500\u2500 kustomization.yaml\n\u251c\u2500\u2500 namespace.yaml\n\u251c\u2500\u2500 releases.yaml\n\u2514\u2500\u2500 source.yaml\nOnce Flux reconciles this directory to the cluster, Flagger and the load tester app should be installed.
Before proceeding to the next step, check that all of your Flagger pods have started successfully:
> kubectl get pods -n flagger\nNAME READY STATUS RESTARTS AGE\nflagger-7d456d4fc7-knf2g 1/1 Running 0 4m\nloadtester-855b4d77f6-scl6r 1/1 Running 0 4m\nWhen Flagger is configured to integrate with a service mesh such as Linkerd or Istio for the rollout, this ClusterRole needs to be extended so that it can read the additional service mesh resources that Flagger generates. To display service mesh- or ingress-related resources, we require spec.provider to be set in each canary resource.
The following table provides a list of all the custom resources that Flagger generates grouped by provider:
Provider API Group Resource AppMesh appmesh.k8s.aws virtualnode appmesh.k8s.aws virtualrouter appmesh.k8s.aws virtualservice Linkerd split.smi-spec.io trafficsplit Istio networking.istio.io destinationrule networking.istio.io virtualservice Contour projectcontour.io httpproxy Gloo gateway.solo.io routetable gloo.solo.io upstream Nginx networking.k8s.io ingress Skipper networking.k8s.io ingress Traefik traefik.containo.us traefikservice Open Service Mesh split.smi-spec.io trafficsplit Kuma kuma.io trafficroute GatewayAPI gateway.networking.k8s.io httprouteFor example, the following manifest shows how gitops-canaries-reader has been extended to allow the user for viewing TrafficSplit resources when Linkerd is used:
apiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRole\nmetadata:\nname: gitops-canaries-reader\nrules:\n- apiGroups:\n- flagger.app\nresources:\n- canaries\n- metrictemplates\nverbs:\n- get\n- list\n- apiGroups:\n- \"\"\nresources:\n- events\nverbs:\n- get\n- watch\n- list\n# Additional permissions for Linkerd resources are added below\n- apiGroups:\n- split.smi-spec.io\nresources:\n- trafficsplits\nverbs:\n- get\n- list\nIn order to view canaries in a remote cluster from the management cluster, you need to consider the following: - The service account used to access the remote cluster needs to be able to list namespaces and custom resource definitions in the given cluster. It additionally needs to be able to impersonate users and groups. - The user or group that logs in to the management cluster, needs appropriate permissions to certain resources of the remote cluster.
For example, applying the following manifest on remote clusters, ensures that the wego-admin user will be able to view canary information from within the Weave GitOps Enterprise UI on the management cluster:
apiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRole\nmetadata:\nname: user-groups-impersonator\nrules:\n- apiGroups: [\"\"]\nresources: [\"users\", \"groups\"]\nverbs: [\"impersonate\"]\n- apiGroups: [\"\"]\nresources: [\"namespaces\"]\nverbs: [\"get\", \"list\"]\n- apiGroups: [\"apiextensions.k8s.io\"]\nresources: [\"customresourcedefinitions\"]\nverbs: [\"get\", \"list\"]\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRoleBinding\nmetadata:\nname: impersonate-user-groups\nsubjects:\n- kind: ServiceAccount\nname: remote-cluster-01 # Service account created in remote cluster\nnamespace: default\nroleRef:\nkind: ClusterRole\nname: user-groups-impersonator\napiGroup: rbac.authorization.k8s.io\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRole\nmetadata:\nname: canary-reader\nrules:\n- apiGroups: [\"\"]\nresources: [ \"events\", \"services\" ]\nverbs: [ \"get\", \"list\", \"watch\" ]\n- apiGroups: [ \"apps\" ]\nresources: [ \"*\" ]\nverbs: [ \"get\", \"list\" ]\n- apiGroups: [ \"autoscaling\" ]\nresources: [ \"*\" ]\nverbs: [ \"get\", \"list\" ]\n- apiGroups: [ \"flagger.app\" ]\nresources: [ \"canaries\", \"metrictemplates\"]\nverbs: [ \"get\", \"list\", \"watch\" ]\n- apiGroups: [ \"helm.toolkit.fluxcd.io\" ]\nresources: [ \"helmreleases\" ]\nverbs: [ \"get\", \"list\" ]\n- apiGroups: [ \"kustomize.toolkit.fluxcd.io\" ]\nresources: [ \"kustomizations\" ]\nverbs: [ \"get\", \"list\" ]\n- apiGroups: [ \"source.toolkit.fluxcd.io\" ]\nresources: [ \"buckets\", \"helmcharts\", \"gitrepositories\", \"helmrepositories\", \"ocirepositories\" ]\nverbs: [ \"get\", \"list\" ]\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: ClusterRoleBinding\nmetadata:\nname: read-canaries\nsubjects:\n- kind: User\nname: wego-admin # User logged in management cluster, impersonated via service account\napiGroup: rbac.authorization.k8s.io\nroleRef:\nkind: ClusterRole\nname: canary-reader\napiGroup: rbac.authorization.k8s.io\nYou may need to add more users/groups to the read-canaries ClusterRoleBinding to ensure additional users can view canary information from within the Weave GitOps Enterprise UI.
To demonstrate the progressive rollout of an application, we'll use a tiny sample web app called podinfo and configure a canary release strategy.
In our example, Flagger will scale up a new version of podinfo (the canary) alongside the existing version (the primary). It will gradually increase traffic to the new version in increments of 5%, up to a maximum of 50%. Flagger will continuously monitor the new version for an acceptable request response rate and average request duration. Based on this analysis, Flagger will either update the primary to the new version or abandon the promotion, then scale the canary back down to zero.
Create a new test directory and add these three canary resource manifests under it: - A Namespace resource to control where the components are installed - A Deployment and HorizontalPodAutoscaler for the podinfo application - A Canary resource which references the Deployment and HorizontalPodAutoscaler resources
We don't need to define a service resource. This is specified within the canary definition and created by Flagger.
Expand to see the three canary resource manifests test/namespace.yaml---\napiVersion: v1\nkind: Namespace\nmetadata:\nname: test\nannotations:\nlinkerd.io/inject: enabled\n---\napiVersion: apps/v1\nkind: Deployment\nmetadata:\nname: podinfo\nlabels:\napp: podinfo\nspec:\nminReadySeconds: 5\nrevisionHistoryLimit: 5\nprogressDeadlineSeconds: 60\nstrategy:\nrollingUpdate:\nmaxUnavailable: 1\ntype: RollingUpdate\nselector:\nmatchLabels:\napp: podinfo\ntemplate:\nmetadata:\nannotations:\nprometheus.io/scrape: \"true\"\nprometheus.io/port: \"9797\"\nlabels:\napp: podinfo\nspec:\ncontainers:\n- name: podinfod\nimage: ghcr.io/stefanprodan/podinfo:6.1.8\nimagePullPolicy: IfNotPresent\nports:\n- name: http\ncontainerPort: 9898\nprotocol: TCP\n- name: http-metrics\ncontainerPort: 9797\nprotocol: TCP\n- name: grpc\ncontainerPort: 9999\nprotocol: TCP\ncommand:\n- ./podinfo\n- --port=9898\n- --port-metrics=9797\n- --grpc-port=9999\n- --grpc-service-name=podinfo\n- --level=info\n- --random-delay=false\n- --random-error=false\nenv:\n- name: PODINFO_UI_COLOR\nvalue: \"#34577c\"\nlivenessProbe:\nexec:\ncommand:\n- podcli\n- check\n- http\n- localhost:9898/healthz\ninitialDelaySeconds: 5\ntimeoutSeconds: 5\nreadinessProbe:\nexec:\ncommand:\n- podcli\n- check\n- http\n- localhost:9898/readyz\ninitialDelaySeconds: 5\ntimeoutSeconds: 5\nresources:\nlimits:\ncpu: 2000m\nmemory: 512Mi\nrequests:\ncpu: 100m\nmemory: 64Mi\n\n---\napiVersion: autoscaling/v2beta2\nkind: HorizontalPodAutoscaler\nmetadata:\nname: podinfo\nspec:\nscaleTargetRef:\napiVersion: apps/v1\nkind: Deployment\nname: podinfo\nminReplicas: 2\nmaxReplicas: 4\nmetrics:\n- type: Resource\nresource:\nname: cpu\ntarget:\ntype: Utilization\n# scale up if usage is above\n# 99% of the requested CPU (100m)\naverageUtilization: 99\n---\napiVersion: flagger.app/v1beta1\nkind: Canary\nmetadata:\nname: podinfo\nspec:\n# deployment reference\ntargetRef:\napiVersion: apps/v1\nkind: Deployment\nname: podinfo\n# HPA reference (optional)\nautoscalerRef:\napiVersion: autoscaling/v2beta2\nkind: HorizontalPodAutoscaler\nname: podinfo\n# the maximum time in seconds for the canary deployment\n# to make progress before it is rollback (default 600s)\nprogressDeadlineSeconds: 60\nservice:\n# ClusterIP port number\nport: 9898\n# container port number or name (optional)\ntargetPort: 9898\nanalysis:\n# schedule interval (default 60s)\ninterval: 30s\n# max number of failed metric checks before rollback\nthreshold: 5\n# max traffic percentage routed to canary\n# percentage (0-100)\nmaxWeight: 50\n# canary increment step\n# percentage (0-100)\nstepWeight: 5\n# Linkerd Prometheus checks\nmetrics:\n- name: request-success-rate\n# minimum req success rate (non 5xx responses)\n# percentage (0-100)\nthresholdRange:\nmin: 99\ninterval: 1m\n- name: request-duration\n# maximum req duration P99\n# milliseconds\nthresholdRange:\nmax: 500\ninterval: 30s\n# testing (optional)\nwebhooks:\n- name: acceptance-test\ntype: pre-rollout\nurl: http://loadtester.flagger/\ntimeout: 30s\nmetadata:\ntype: bash\ncmd: \"curl -sd 'test' http://podinfo-canary.test:9898/token | grep token\"\n- name: load-test\ntype: rollout\nurl: http://loadtester.flagger/\nmetadata:\ncmd: \"hey -z 2m -q 10 -c 2 http://podinfo-canary.test:9898/\"\nAdd a Kustomization file to apply all resources to the test namespace:
---\napiVersion: kustomize.config.k8s.io/v1beta1\nkind: Kustomization\nnamespace: test\nresources:\n- namespace.yaml\n- deployment.yaml\n- canary.yaml\nAt this point, the test directory in the cluster repository should look like this:
> tree test\ntest\n\u251c\u2500\u2500 canary.yaml\n\u251c\u2500\u2500 deployment.yaml\n\u251c\u2500\u2500 kustomization.yaml\n\u2514\u2500\u2500 namespace.yaml\nAfter a short time, the status of the canary object should be set to Initialized:
> kubectl get canary podinfo -n test\nNAME STATUS WEIGHT LASTTRANSITIONTIME\npodinfo Initialized 0 2022-07-22T12:37:58Z\nTrigger a new rollout by bumping the version of podinfo:
> kubectl set image deployment/podinfo podinfod=ghcr.io/stefanprodan/podinfo:6.0.1 -n test\nDuring the progressive rollout, the canary object reports on its current status:
> kubectl get canary podinfo -n test\nNAME STATUS WEIGHT LASTTRANSITIONTIME\npodinfo Progressing 5 2022-07-22T12:41:57Z\nAfter a short time the rollout is completed and the status of the canary object is set to Succeeded:
> kubectl get canary podinfo -n test\nNAME STATUS WEIGHT LASTTRANSITIONTIME\npodinfo Succeeded 0 2022-07-22T12:47:58Z\nCongratulations, you have now completed a progressive delivery rollout with Flagger and Linkerd!
Next steps: - Explore more of what Flagger offers - Configure manual approvals for progressive delivery deployments
"},{"location":"references/helm-reference/","title":"Helm chart reference","text":"This is a reference of all the configurable values in Weave GitOps's Helm chart. This is intended for customizing your installation after you've gone through the getting started guide.
This reference was generated for the chart version 4.0.34 which installs weave gitops v0.36.0.
"},{"location":"references/helm-reference/#values","title":"Values","text":"Key Type Default Description additionalArgs list[] Additional arguments to pass in to the gitops-server adminUser.create bool false Whether the local admin user should be created. If you use this make sure you add it to rbac.impersonationResourceNames. adminUser.createClusterRole bool true Specifies whether the clusterRole & binding to the admin user should be created. Will be created only if adminUser.create is enabled. Without this, the adminUser will only be able to see resources in the target namespace. adminUser.createSecret bool true Whether we should create the secret for the local adminUser. Will be created only if adminUser.create is enabled. Without this, we'll still set up the roles and permissions, but the secret with username and password has to be provided separately. adminUser.passwordHash string nil Set the password for local admin user. Requires adminUser.create and adminUser.createSecret This needs to have been hashed using bcrypt. You can do this via our CLI with gitops get bcrypt-hash. adminUser.username string \"gitops-test-user\" Set username for local admin user, this should match the value in the secret cluster-user-auth which can be created with adminUser.createSecret. Requires adminUser.create. affinity object {} annotations object {} Annotations to add to the deployment envVars[0].name string \"WEAVE_GITOPS_FEATURE_TENANCY\" envVars[0].value string \"true\" envVars[1].name string \"WEAVE_GITOPS_FEATURE_CLUSTER\" envVars[1].value string \"false\" extraVolumeMounts list [] extraVolumes list [] fullnameOverride string \"\" image.pullPolicy string \"IfNotPresent\" image.repository string \"ghcr.io/weaveworks/wego-app\" image.tag string \"v0.36.0\" imagePullSecrets list [] ingress.annotations object {} ingress.className string \"\" ingress.enabled bool false ingress.hosts string nil ingress.tls list [] logLevel string \"info\" What log level to output. Valid levels are 'debug', 'info', 'warn' and 'error' metrics.enabled bool false Start the metrics exporter metrics.service.annotations object {\"prometheus.io/path\":\"/metrics\",\"prometheus.io/port\":\"{{ .Values.metrics.service.port }}\",\"prometheus.io/scrape\":\"true\"} Annotations to set on the service metrics.service.port int 2112 Port to start the metrics exporter on nameOverride string \"\" networkPolicy.create bool true Specifies whether default network policies should be created. nodeSelector object {} oidcSecret.create bool false podAnnotations object {} podLabels object {} podSecurityContext object {} rbac.additionalRules list [] If non-empty, these additional rules will be appended to the RBAC role and the cluster role. for example, additionalRules: - apiGroups: [\"infra.contrib.fluxcd.io\"] resources: [\"terraforms\"] verbs: [ \"get\", \"list\", \"patch\" ] rbac.create bool true Specifies whether the clusterRole & binding to the service account should be created rbac.impersonationResourceNames list [] If non-empty, this limits the resources that the service account can impersonate. This applies to both users and groups, e.g. ['user1@corporation.com', 'user2@corporation.com', 'operations'] rbac.impersonationResources list [\"users\",\"groups\"] Limit the type of principal that can be impersonated rbac.viewSecretsResourceNames list [\"cluster-user-auth\",\"oidc-auth\"] If non-empty, this limits the secrets that can be accessed by the service account to the specified ones, e.g. ['weave-gitops-enterprise-credentials'] replicaCount int 1 resources object {} securityContext.allowPrivilegeEscalation bool false securityContext.capabilities.drop[0] string \"ALL\" securityContext.readOnlyRootFilesystem bool true securityContext.runAsNonRoot bool true securityContext.runAsUser int 1000 securityContext.seccompProfile.type string \"RuntimeDefault\" serverTLS.enable bool false Enable TLS termination in gitops itself. If you enable this, you need to create a secret, and specify the secretName. Another option is to create an ingress. serverTLS.secretName string \"my-secret-tls\" Specify the tls secret name. This type of secrets have a key called tls.crt and tls.key containing their corresponding values in base64 format. See https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets for more details and examples service.annotations object {} service.create bool true service.port int 9001 service.type string \"ClusterIP\" serviceAccount.annotations object {} Annotations to add to the service account serviceAccount.create bool true Specifies whether a service account should be created serviceAccount.name string \"\" The name of the service account to use. If not set and create is true, a name is generated using the fullname template tolerations list []"},{"location":"references/cli-reference/gitops/","title":"Gitops","text":""},{"location":"references/cli-reference/gitops/#gitops","title":"gitops","text":"Weave GitOps
"},{"location":"references/cli-reference/gitops/#synopsis","title":"Synopsis","text":"Command line utility for managing Kubernetes applications via GitOps.
"},{"location":"references/cli-reference/gitops/#examples","title":"Examples","text":" # Get help for gitops create dashboard command\n gitops create dashboard -h\n gitops help create dashboard\n\n # Get the version of gitops along with commit, branch, and flux version\n gitops version\n\n To learn more, you can find our documentation at https://docs.gitops.weave.works/\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n -h, --help help for gitops\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nValidates flux compatibility
gitops check [flags]\n# Validate flux and kubernetes compatibility\ngitops check\n -h, --help help for check\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nGenerate the autocompletion script for the specified shell
"},{"location":"references/cli-reference/gitops_completion/#synopsis","title":"Synopsis","text":"Generate the autocompletion script for gitops for the specified shell. See each sub-command's help for details on how to use the generated script.
"},{"location":"references/cli-reference/gitops_completion/#options","title":"Options","text":" -h, --help help for completion\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nGenerate the autocompletion script for bash
"},{"location":"references/cli-reference/gitops_completion_bash/#synopsis","title":"Synopsis","text":"Generate the autocompletion script for the bash shell.
This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager.
To load completions in your current shell session:
source <(gitops completion bash)\nTo load completions for every new session, execute once:
"},{"location":"references/cli-reference/gitops_completion_bash/#linux","title":"Linux:","text":"gitops completion bash > /etc/bash_completion.d/gitops\ngitops completion bash > $(brew --prefix)/etc/bash_completion.d/gitops\nYou will need to start a new shell for this setup to take effect.
gitops completion bash\n -h, --help help for bash\n --no-descriptions disable completion descriptions\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nGenerate the autocompletion script for fish
"},{"location":"references/cli-reference/gitops_completion_fish/#synopsis","title":"Synopsis","text":"Generate the autocompletion script for the fish shell.
To load completions in your current shell session:
gitops completion fish | source\nTo load completions for every new session, execute once:
gitops completion fish > ~/.config/fish/completions/gitops.fish\nYou will need to start a new shell for this setup to take effect.
gitops completion fish [flags]\n -h, --help help for fish\n --no-descriptions disable completion descriptions\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nGenerate the autocompletion script for powershell
"},{"location":"references/cli-reference/gitops_completion_powershell/#synopsis","title":"Synopsis","text":"Generate the autocompletion script for powershell.
To load completions in your current shell session:
gitops completion powershell | Out-String | Invoke-Expression\nTo load completions for every new session, add the output of the above command to your powershell profile.
gitops completion powershell [flags]\n -h, --help help for powershell\n --no-descriptions disable completion descriptions\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nGenerate the autocompletion script for zsh
"},{"location":"references/cli-reference/gitops_completion_zsh/#synopsis","title":"Synopsis","text":"Generate the autocompletion script for the zsh shell.
If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:
echo \"autoload -U compinit; compinit\" >> ~/.zshrc\nTo load completions in your current shell session:
source <(gitops completion zsh)\nTo load completions for every new session, execute once:
"},{"location":"references/cli-reference/gitops_completion_zsh/#linux","title":"Linux:","text":"gitops completion zsh > \"${fpath[1]}/_gitops\"\ngitops completion zsh > $(brew --prefix)/share/zsh/site-functions/_gitops\nYou will need to start a new shell for this setup to take effect.
gitops completion zsh [flags]\n -h, --help help for zsh\n --no-descriptions disable completion descriptions\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nCreates a resource
"},{"location":"references/cli-reference/gitops_create/#examples","title":"Examples","text":"# Create a HelmRepository and HelmRelease to deploy Weave GitOps\ngitops create dashboard ww-gitops \\\n --password=$PASSWORD \\\n --export > ./clusters/my-cluster/weave-gitops-dashboard.yaml\n\n# Create a Terraform object\ngitops create terraform my-resource \\\n -n my-namespace \\\n --source GitRepository/my-project \\\n --path ./terraform \\\n --interval 1m \\\n --export > ./clusters/my-cluster/infra/terraform-my-resource.yaml\n --export Export in YAML format to stdout.\n -h, --help help for create\n --timeout duration The timeout for operations during resource creation. (default 3m0s)\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nCreate a HelmRepository and HelmRelease to deploy Weave GitOps
"},{"location":"references/cli-reference/gitops_create_dashboard/#synopsis","title":"Synopsis","text":"Create a HelmRepository and HelmRelease to deploy Weave GitOps
gitops create dashboard [flags]\n# Create a HelmRepository and HelmRelease to deploy Weave GitOps\ngitops create dashboard ww-gitops \\\n --password=$PASSWORD \\\n --export > ./clusters/my-cluster/weave-gitops-dashboard.yaml\n --context string The name of the kubeconfig context to use\n --disable-compression If true, opt-out of response compression for all requests to the server\n -h, --help help for dashboard\n --password string The password of the dashboard admin user.\n --username string The username of the dashboard admin user. (default \"admin\")\n --values strings Local path to values.yaml files for HelmRelease, also accepts comma-separated values.\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --export Export in YAML format to stdout.\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n --timeout duration The timeout for operations during resource creation. (default 3m0s)\nCreate a Terraform object
"},{"location":"references/cli-reference/gitops_create_terraform/#synopsis","title":"Synopsis","text":"Create a Terraform object
gitops create terraform [flags]\n# Create a Terraform resource in the default namespace\ngitops create terraform -n default my-resource --source GitRepository/my-project --path ./terraform --interval 15m\n\n# Create and export a Terraform resource manifest to the standard output\ngitops create terraform -n default my-resource --source GitRepository/my-project --path ./terraform --interval 15m --export\n --context string The name of the kubeconfig context to use\n --disable-compression If true, opt-out of response compression for all requests to the server\n -h, --help help for terraform\n --interval string Interval at which the Terraform configuration should be applied\n --path string Path to the Terraform configuration\n --source string Source of the Terraform configuration\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --export Export in YAML format to stdout.\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n --timeout duration The timeout for operations during resource creation. (default 3m0s)\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nDelete a resource
"},{"location":"references/cli-reference/gitops_delete/#options","title":"Options","text":" -h, --help help for delete\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nDelete a Terraform object
gitops delete terraform [flags]\n# Delete a Terraform resource in the default namespace\ngitops delete terraform -n default my-resource\n --context string The name of the kubeconfig context to use\n --disable-compression If true, opt-out of response compression for all requests to the server\n -h, --help help for terraform\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nDisplay one or many Weave GitOps resources
"},{"location":"references/cli-reference/gitops_get/#examples","title":"Examples","text":"# Get the CLI configuration for Weave GitOps\ngitops get config\n\n# Generate a hashed secret\nPASSWORD=\"<your password>\"\necho -n $PASSWORD | gitops get bcrypt-hash\n -h, --help help for get\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nGenerates a hashed secret
gitops get bcrypt-hash [flags]\nPASSWORD=\"<your password>\"\necho -n $PASSWORD | gitops get bcrypt-hash\n -h, --help help for bcrypt-hash\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nPrints out the CLI configuration for Weave GitOps
gitops get config [flags]\n# Prints out the CLI configuration for Weave GitOps\ngitops get config\n -h, --help help for config\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nGet logs for a resource
"},{"location":"references/cli-reference/gitops_logs/#options","title":"Options","text":" -h, --help help for logs\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nGet the runner logs of a Terraform object
gitops logs terraform [flags]\n# Get the runner logs of a Terraform object in the \"flux-system\" namespace\ngitops logs terraform --namespace flux-system my-resource\n --context string The name of the kubeconfig context to use\n --disable-compression If true, opt-out of response compression for all requests to the server\n -h, --help help for terraform\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nReplan a resource
"},{"location":"references/cli-reference/gitops_replan/#examples","title":"Examples","text":"# Replan the Terraform plan of a Terraform object from the \"flux-system\" namespace\ngitops replan terraform --namespace flux-system my-resource\n -h, --help help for replan\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nTrigger replan for a Terraform object
gitops replan terraform [flags]\n# Replan the Terraform plan of a Terraform object from the \"flux-system\" namespace\ngitops replan terraform --namespace flux-system my-resource\n --context string The name of the kubeconfig context to use\n --disable-compression If true, opt-out of response compression for all requests to the server\n -h, --help help for terraform\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nResume a resource
"},{"location":"references/cli-reference/gitops_resume/#examples","title":"Examples","text":"# Suspend a Terraform object from the \"flux-system\" namespace\ngitops resume terraform --namespace flux-system my-resource\n -h, --help help for resume\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nResume a Terraform object
gitops resume terraform [flags]\n# Resume a Terraform object in the \"flux-system\" namespace\ngitops resume terraform --namespace flux-system my-resource\n --context string The name of the kubeconfig context to use\n --disable-compression If true, opt-out of response compression for all requests to the server\n -h, --help help for terraform\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nSets one or many Weave GitOps CLI configs or resources
"},{"location":"references/cli-reference/gitops_set/#examples","title":"Examples","text":"# Enables analytics in the current user's CLI configuration for Weave GitOps\ngitops set config analytics true\n -h, --help help for set\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nSet the CLI configuration for Weave GitOps
gitops set config [flags]\n# Enables analytics in the current user's CLI configuration for Weave GitOps\ngitops set config analytics true\n -h, --help help for config\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nSuspend a resource
"},{"location":"references/cli-reference/gitops_suspend/#examples","title":"Examples","text":"# Suspend a Terraform object in the \"flux-system\" namespace\ngitops resume terraform --namespace flux-system my-resource\n -h, --help help for suspend\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nSuspend a Terraform object
gitops suspend terraform [flags]\n# Suspend a Terraform object in the \"flux-system\" namespace\ngitops suspend terraform --namespace flux-system my-resource\n --context string The name of the kubeconfig context to use\n --disable-compression If true, opt-out of response compression for all requests to the server\n -h, --help help for terraform\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nDisplay gitops version
gitops version [flags]\n -h, --help help for version\n -e, --endpoint WEAVE_GITOPS_ENTERPRISE_API_URL The Weave GitOps Enterprise HTTP API endpoint can be set with WEAVE_GITOPS_ENTERPRISE_API_URL environment variable\n --insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure\n --kubeconfig string Paths to a kubeconfig. Only required if out-of-cluster.\n -n, --namespace string The namespace scope for this operation (default \"flux-system\")\n -p, --password WEAVE_GITOPS_PASSWORD The Weave GitOps Enterprise password for authentication can be set with WEAVE_GITOPS_PASSWORD environment variable\n -u, --username WEAVE_GITOPS_USERNAME The Weave GitOps Enterprise username for authentication can be set with WEAVE_GITOPS_USERNAME environment variable\nSecrets are sensitive information such as passwords, access keys, and other credentials that should not be exposed publicly. In cloud-native applications, secrets are often used to authenticate and authorize access to various resources, such as databases, APIs, and other services.
In a GitOps environment, secrets are typically stored either encrypted in Git, or using Custom Resources that reference the secret in an external secret store. Secrets are then synced into the clusters and securely passed to the application containers or workloads.
Effective secrets management in cloud-native applications and GitOps environments is critical for maintaining the security and compliance of the overall system. Best practices include regularly rotating secrets, using strong encryption and access controls, and implementing robust auditing and monitoring processes.
"},{"location":"secrets/#weave-gitops-secrets-management","title":"Weave Gitops Secrets Management","text":"Weave GitOps Secrets Management is a set of features that makes it easier for teams to manage secrets in a GitOps environment across multiple clusers. These features provide an automated way to manage secrets effectively, and make it easier for different personas to work with secrets.
For Developers, they can use Weave GitOps Secrets Management to securely create and track application secrets such as API keys, passwords, and other credentials. They can do that using Weave GitOps UI in a self-serve manner.
For Operation Teams, they can use Weave GitOps Secrets Management to help set up secure and reliable flows for developers to create and consume secrets for their applications.
Weave GitOps Secrets Management supports integrations with SOPS and External Secrets Operator (ESO) to provide a secure and automated way to manage secrets in a GitOps environment, while giving the option for customers to choose any of these secrets operators or working with both of them.
For SOPS and ESO operators, Weave GitOps is providing different ways to do the following: * Setup Secrets Operators (SOPS | ESO) * Bootstrap Secrets into clusters * Manage Secrets through Weave GitOps UI
In order to get started with WeaveGitOps Secrets Management, please follow this guide here.
"},{"location":"secrets/bootstrapping-secrets/","title":"Bootstrapping Secrets ENTERPRISE","text":"When accessing protected resources there is a need for a client to authenticate before the access is granted and the resource is consumed. For authentication, a client presents credentials that are either created manually or available through infrastructure. A common scenario is to have a secrets store.
Weave Gitops allows you to provision the secret management infrastructure as part of its capabilities. However, in order to provision, as any other application that has secrets, we need to create the secret needed for installing it. This is known as a chicken-egg scenario that get addressed by providing an initial secret. This secret we call it bootstrapping secret.
Bootstrapping secrets comes in handy, not only while provisioning your secrets management solution, but also in any platform provisioning task where the existence of the secret is a prerequisite. Another common example could be provisioning platform capabilities via profiles that are stored in private repositories.
Weave Gitops provides SecretSync as a solution to managing your bootstrapping secrets.
"},{"location":"secrets/bootstrapping-secrets/#secretsync","title":"SecretSync","text":"Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
SecretSync is a Kubernetes Custom Resource that provides semantics to sync Kuberentes Secrets from management cluster to leaf clusters.
An example could be seen below:
apiVersion: capi.weave.works/v1alpha1\nkind: SecretSync\nmetadata:\nname: my-dev-secret-syncer\nnamespace: default\nspec:\nclusterSelector:\nmatchLabels:\nenvironment: dev\nsecretRef:\nname: my-dev-secret\ntargetNamespace: my-namespace\n1) Select the secret to sync:
secretRef:\nname: my-dev-secret\n2) Specify the GitopsClusters that the secret will be synced to via labels:
clusterSelector:\nmatchLabels:\nenvironment: dev\nSecretsync reconciles secrets on clusters: any cluster at a future time matching the label selector will have the secret reconciled too.
More info about the CRD spec here
"},{"location":"secrets/bootstrapping-secrets/#working-with-secretsync","title":"Working with SecretSync","text":""},{"location":"secrets/bootstrapping-secrets/#pre-requisites","title":"Pre-requisites","text":"apiVersion: gitops.weave.works/v1alpha1\nkind: GitopsCluster\nmetadata:\nnamespace: flux-system\nlabels:\nenvironment: dev\napiVersion: v1\nkind: Secret\nmetadata:\nname: my-dev-secret\nnamespace: flux-system\ntype: Opaque\nInfo
Some restriction apply to the current version: - Resources should be in the same namespace - Leaf cluster nodes should be annotated with node-role.kubernetes.io/control-plane
apiVersion: capi.weave.works/v1alpha1\nkind: SecretSync\nmetadata:\nname: my-dev-secret-syncer\nnamespace: default\nspec:\nclusterSelector:\nmatchLabels:\nenvironment: dev\nsecretRef:\nname: my-dev-secret\ntargetNamespace: my-namespace\nOnce reconciled, the status section would show created secret resource version
status:\n versions:\n leaf-cluster-1: \"211496\"\nYour secret has been created in the target leaf cluster
\u279c kubectl get secret -n default\nNAME TYPE DATA\nmy-dev-secret Opaque 1\nWarning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
This guide shows you a basic experience to get started with Weave Gitops Secrets. It covers the scenario of setting up the capability in a test environment and how to use it for your applications.
"},{"location":"secrets/getting-started/#requirements","title":"Requirements","text":"In order to be able to manage external secrets stores and secrets, add external-secrets application from weaveworks-charts profiles repository.
Include via values.yaml the configuration to deploy the SecretStore connecting to AWS Secrets Manager.
values:\nsecretStores:\nenabled: true\npath: ./clusters/bases/secrets\nsourceRef:\nkind: GitRepository\nname: flux-system\nnamespace: flux-system\nclusters/bases/secrets in our configuration repo where a kustomization exists apiVersion: kustomize.config.k8s.io/v1beta1\nkind: Kustomization\nresources:\n- aws-secrets-manager.yaml\nWith the AWS Secrets Manager secret store
apiVersion: external-secrets.io/v1beta1\nkind: SecretStore\nmetadata:\nname: aws-secrets-manager\nnamespace: flux-system\nspec:\nprovider:\naws:\nauth:\nsecretRef:\naccessKeyIDSecretRef:\nkey: access-key\nname: awssm-secret\nsecretAccessKeySecretRef:\nkey: secret-access-key\nname: awssm-secret\nregion: eu-north-1\nservice: SecretsManager\nReview and merge the PR and see it available in your cluster
"},{"location":"secrets/getting-started/#create-the-secret","title":"Create the secret","text":"Given you have a secret in AWS Secrets Manager for example test/search/db.
Create the External Secret manifest via Secrets UI to pull the secret from your store into your environment.
See it available in your cluster.
"},{"location":"secrets/getting-started/#use-the-secret","title":"Use the secret","text":"At this stage you have everything you need for your application to consume the secret. Add it to your application as usual.
Expand to see exampleapiVersion: v1\nkind: Pod\nmetadata:\nname: secret-dotfiles-pod\nspec:\nvolumes:\n- name: database-secrets\nsecret:\nsecretName: search-database\ncontainers:\n- name: dotfile-test-container\nimage: registry.k8s.io/busybox\ncommand:\n- ls\n- \"-l\"\n- \"/etc/database-secrets\"\nvolumeMounts:\n- name: database-secrets\nreadOnly: true\nmountPath: \"/etc/database-secrets\"\nYou could see the expected secret available
kubectl logs -f secret-dotfiles-pod\n\ntotal 0\nlrwxrwxrwx 1 root root 15 Apr 5 17:26 password -> ..data/password\nAt Weave GitOps Enterprise (WGE), we support two approaches for creating and managing secrets: External Secrets Operator and Mozilla SOPS. In this guide, we will provide an overview of both approaches and explain how to use the UI to create and manage secrets.
Clicking on the Secrets under the Platform section in the left hand menu will bring you to the secrets page where you can create external secrets, sops secrets, and view the external secrets list.
"},{"location":"secrets/manage-secrets-ui/#external-secrets","title":"External Secrets","text":""},{"location":"secrets/manage-secrets-ui/#prerequisites","title":"Prerequisites","text":"Setup the External Secrets Operator by following this guide.
"},{"location":"secrets/manage-secrets-ui/#create-external-secret-cr","title":"Create External Secret CR","text":"To create a new ExternalSecret CR, start by clicking on to the Create External Secret button to navigate to the creation page.
Here, you will be prompted to enter the External Secret Name and the Target K8s Secret Name. Once you choose the Target Cluster, you will find a new list of all the Secret Stores on this cluster to choose from.
It's important to note that the chosen SecretStore may be a cluster-scoped SecretStore ie: ClusterSecretStore or a namespace-scoped SecretStore.
If you choose a namespace scoped SecretStore, the new secret will be created on the same namespace as the SecretStore.
If you choose a cluster-scoped ClusterSecretStore, the new secret will be created in a namespace of your choice.
Then you need to add the SecretPath, which is the path to the external secret within the secret store.
After you have chosen your desired SecretStore & SecretPath the UI allows you to add secret properties in two differen scenarios:
The first scenario allows you to add specific property fields. Each added property also has an optional SecretKey field. Here's how to do it:
In the Properties section, click the Add button to create a new property field.
Enter the name of the property you want to create. You can add as many properties as you need.
If you wish to specify a SecretKey for the property, enter it in the SecretKey field. If this field is left blank, the property name will be used as the SecretKey.
To remove a property, click the Remove sign next to the property you wish to delete.
Remember, this option allows you to have fine-grained control over which properties are included in your ExternalSecret.
The second scenario is to include all properties in your ExternalSecret. If the Include all properties checkbox is checked, all property inputs will be disabled and ignored, and all secrets including all keys under the specified SecretPath will be added. Here's how:
Check the Include all properties checkbox. This will automatically disable the property input fields.
Using this option allows you to quickly create an ExternalSecret that includes all secrets under a specific SecretPath, without the need to specify each one individually.
Warning
Remember to use this option with caution. You may not need to expose all your secret properties to be on the cluster.
This process allows you to easily create new ExternalSecret CRs without needing to manually create them through YAML files or command line tools.
The ExternalSecrets List section of the UI allows you to view all the external secrets that are currently stored in your Kubernetes clusters. This section provides an overview of each external secret, including its name, namespace, cluster, k8s-secret, secret-store and the age. From this page, you can also navigate to the details page to view more information about a specific secret.
"},{"location":"secrets/manage-secrets-ui/#external-secret-details","title":"External Secret Details","text":"The details page displays the details of a specific external secret, including its name, namespace, data, and creation date. Below are the details that you can expect to see on this page:
Based on the configuration of the external secret, this section will vary:
Understanding the information provided on the details page can help you to manage and troubleshoot your external secrets as needed.
"},{"location":"secrets/manage-secrets-ui/#properties","title":"Properties","text":""},{"location":"secrets/manage-secrets-ui/#understanding-events","title":"Understanding Events","text":"The following events can be expected when using the UI to manage external secrets:
Understanding these events can help you to troubleshoot issues that may arise when managing external secrets using the UI. In particular, if you encounter a Not Ready event, you may need to check your secret store credentials and ensure that the secret store is operational before proceeding with any further actions.
Creating a SOPS secret involves using the SOPS tool to encrypt a file containing sensitive information, such as credentials or API keys. This encrypted file can then be stored securely in version control or another location, with only authorized users able to decrypt it using their own private key. This adds an additional layer of security to sensitive data, reducing the risk of unauthorized access or accidental exposure.
"},{"location":"secrets/manage-secrets-ui/#prerequisites_1","title":"Prerequisites","text":"For more information about how to generate OpenPGP/age keys and configure your cluster to work with Weave GitOps Enterprise secrets management follow this guide.
"},{"location":"secrets/manage-secrets-ui/#create-sops-secret","title":"Create SOPS Secret","text":"To create a new SOPS secret, start by clicking on the Create Sops Secret button.
This will open the create form where you can specify the details of your new secret. First, choose the Cluster where you want to create the secret. Then, enter a name for your secret and select the namespace where it will be created.
Next, select the encryption method that you want to use - currently, only GPG/AGE encryption is supported. Finally, choose the kustomization that will be used by SOPS to decrypt the secret, as well as, having the public key info that will be used to encrypt the secret data. Afterwards, add your key-value pairs of your secrets. It's important to note that the value input will be encoded to base64.
The generated secret should be something like below.
After approving the pull request, Flux will reconcile it to your cluster. To verify that the secret has been successfully created, you can use the following command to retrieve it as YAML:
kubectl get secret secretTest-default-sops-secret -n default -o yaml\nwhich will give the following output:
apiVersion: v1\ndata:\nsecret-1: dmFsCg==\nkind: Secret\nmetadata:\nname: secretTest-default-sops-secret\nnamespace: default\ntype: Opaque\nWeave GitOps Enterprise now supports managing secrets using External Secrets Operator from the UI. External Secrets Operator is a Kubernetes operator that allows users to use secrets from external secrets management systems by reading their information using external APIs and injecting their values into Kubernetes secrets. To be able to use this functionality, users need to configure their External Secrets Operator and SecretStores using one of the guides below.
"},{"location":"secrets/setup-eso/#prerequisites","title":"Prerequisites","text":""},{"location":"secrets/setup-eso/#secretstores","title":"SecretStores","text":"You should have your SecretStore CRs defined in a git repository. Those CRs will be installed to your cluster in the following steps and used by the creation UI.
"},{"location":"secrets/setup-eso/#eso-profile","title":"ESO Profile","text":"The ESO profile is packaged with the weaveworks-charts. If you have the usual profiles setup, you will not need to do anything extra. This profile installs the ESO controller, all the required CRDs, and the SecretStore CRs defined in the previous step.
"},{"location":"secrets/setup-eso/#secrets","title":"Secrets","text":"There are several Kubernetes Secrets that need to exist on your management cluster for the whole flow to work.
If your SecretStores repository is private then you'll need a Secret, that contains the repo credentials, to access the repository. This is usually the Secret you created while bootstrapping Flux on the management cluster and is copied to your leaf cluster during creation.
For each SecretStore CR, you'll need to add a Secret, that follows the format expected by this CR, to allow the operator to access the defined External Secret Store.
Follow this guide for bootstrapping those secrets on leaf clusters.
"},{"location":"secrets/setup-eso/#installation-steps","title":"Installation Steps","text":""},{"location":"secrets/setup-eso/#install-eso-on-management-cluster-or-existing-leaf-cluster","title":"Install ESO on management cluster or existing leaf cluster","text":"To install the ESO profile on an exisitng cluster, use Add an application from the Applications page and select external-secrets from weaveworks-charts. Check the Profile values section for more info about configuring the values.yaml.
To bootstrap the ESO profile on a leaf cluster, select external-secrets from the profiles dropdown in the Create Cluster page. Check the Profile values section for more info about configuring the values.yaml.
You should then configure the values.yaml to install the SecretStores on the cluster from a GitRepository. This is done by configuring the secretStores section.
secretStores:\nenabled: true\nurl: ssh://git@github.com/github-owner/repo-name # url for the git repository that contains the SecretStores\ntag: v1.0.0\npath: ./ # could be a path to the secrets dir or a kustomization.yaml file for the SecretStore in the GitRepository\nsecretRef: my-pat # the name of the Secret containing the repo credentials for private repositories\nsecretStores:\nenabled: true\nsourceRef: # Specify the name for an existing GitSource reference\nkind: GitRepository\nname: flux-system\nnamespace: flux-system\nimport CodeBlock from \"@theme/CodeBlock\";
import SopsBootstrapJob from \"!!raw-loader!./assets/sops-bootstrap-job.yaml\"; import TemplateParams from \"!!raw-loader!./assets/template-params.yaml\"; import TemplateAnnotations from \"!!raw-loader!./assets/template-annotations.yaml\";
"},{"location":"secrets/setup-sops/#setup-sops-enterprise","title":"Setup SOPS ENTERPRISE","text":"Weave GitOps Enterprise now supports managing secrets using SOPS, a tool that encrypts and decrypts secrets using various key management services, from the UI. To be able to use this functionality, users need to configure their private and public key-pairs using one of the guides below.
"},{"location":"secrets/setup-sops/#setup-sops-on-management-cluster-or-existing-leaf-cluster","title":"Setup SOPS on management cluster or existing leaf cluster","text":"In this section, we will cover the prerequisites for using SOPS with Weave GitOps Enterprise, and how to configure SOPS for your existing Kubernetes cluster to work with GPG and age keys.
For a more advanced setup for SOPS with flux, please refer to this guide.
"},{"location":"secrets/setup-sops/#encrypting-secrets-using-gpgopenpgp","title":"Encrypting secrets using GPG/OpenPGP","text":"OpenPGP is a way of using SOPS to encrypt and decrypt secrets with Weave GitOps Enterprise.
Here are the steps to generate an OpenPGP key and configure your cluster to work with Weave GitOps Enterprise secrets management.
1- Generate a gpg key pairs
Expand for instructionsexport KEY_NAME=\"gpg-key\"\nexport KEY_COMMENT=\"gpg key\"\n\ngpg --batch --full-generate-key <<EOF\n%no-protection\nKey-Type: 1\nKey-Length: 4096\nSubkey-Type: 1\nSubkey-Length: 4096\nExpire-Date: 0\nName-Comment: ${KEY_COMMENT}\nName-Real: ${KEY_NAME}\nEOF\n2- Export the key pairs fingerprint in the shell
gpg --list-secret-keys \"${KEY_NAME}\"\n\nsec rsa4096 2020-09-06 [SC]\n710DC0DB6C1662F707095FC30233CB21E656A3CB\n\nexport KEY_FP=\"710DC0DB6C1662F707095FC30233CB21E656A3CB\"\n3- Export the generated private key to a kubernetes secret sops-gpg-private-key which will be used by flux's kustomize-controller to decrypt the secrets using sops.
gpg --export-secret-keys --armor \"${KEY_FP}\" |\nkubectl create secret generic sops-gpg-private-key \\\n--namespace=flux-system \\\n--from-file=sops.asc=/dev/stdin\n4- Export the generated public key to a kubernetes secret sops-gpg-public-key which will be used by Weave GitOps Enterprise to encrypt the secrets created from the UI.
gpg --export --armor \"${KEY_FP}\" |\nkubectl create secret generic sops-gpg-public-key \\\n--namespace=flux-system \\\n--from-file=sops.asc=/dev/stdin\nTip
It's recommended to remove the secret from your machine
gpg --delete-secret-keys \"${KEY_FP}\"\n5- Create a kustomization for reconciling the secrets on the cluster and set the --decryption-secret flag to the name of the private key created in step 3.
flux create kustomization gpg-secrets \\\n--source=secrets \\ # the git source to reconcile the secrets from\n--path=./secrets/gpg \\\n--prune=true \\\n--interval=10m \\\n--decryption-provider=sops \\\n--decryption-secret=sops-gpg-private-key\n6- Annotate the kustomization object created in the previous step with the name and namespace of the public key created in step 4.
kubectl annotate kustomization gpg-secrets \\\nsops-public-key/name=sops-gpg-public-key \\\nsops-public-key/namespace=flux-system \\\n-n flux-system\napiVersion: kustomize.toolkit.fluxcd.io/v1beta2\nkind: Kustomization\nmetadata:\nname: gpg-secrets\nnamespace: flux-system\nannotations:\nsops-public-key/name: sops-gpg-public-key\nsops-public-key/namespace: flux-system\nspec:\ninterval: 10m\nsourceRef:\nkind: GitRepository\nname: secrets\npath: ./secrets/gpg\ndecryption:\nprovider: sops\nsecretRef:\nname: sops-gpg-private-key\nprune: true\nvalidation: server\nNote
This is an essential step in order to allow other operators and developers to utilize WeaveGitOps UI to encrypt SOPS secrets using the public key secret in the cluster.
"},{"location":"secrets/setup-sops/#encrypting-secrets-using-age","title":"Encrypting secrets using age","text":"age is a simple, modern and secure file encryption tool, that can be used to encrypt secrets using Weave GitOps Enterprise.
Here are the steps to generate an age key and configure your cluster to work with Weave GitOps Enterprise secrets management.
1- Generate an age key with age-keygen
age-keygen -o age.agekey\n\nPublic key: <public key>\n2- Export the generated private key to a kubernetes secret sops-age-private-key which will be used by flux's kustomize-controller to decrypt the secrets using sops.
cat age.agekey |\nkubectl create secret generic sops-age-private-key \\\n--namespace=flux-system \\\n--from-file=age.agekey=/dev/stdin\n4- Export the generated public key to a kubernetes secret sops-age-public-key which will be used by Weave GitOps Enterprise to encrypt the secrets created from the UI.
echo \"<public key>\" |\nkubectl create secret generic sops-age-public-key \\\n--namespace=flux-system \\\n--from-file=age.agekey=/dev/stdin\nTip
It's recommended to remove the secret from your machine
rm -f age.ageKey\n5- Create a kustomization for reconciling the secrets on the cluster and set the --decryption-secret flag to the name of the private key created in step 2.
flux create kustomization age-secrets \\\n--source=secrets \\ # the git source to reconcile the secrets from\n--path=./secrets/age \\\n--prune=true \\\n--interval=10m \\\n--decryption-provider=sops \\\n--decryption-secret=sops-age-private-key\n6- Annotate the kustomization object created in the previous step with the name and namespace of the public key created in step 4.
kubectl annotate kustomization age-secrets \\\nsops-public-key/name=sops-age-public-key \\\nsops-public-key/namespace=flux-system \\\n-n flux-system\napiVersion: kustomize.toolkit.fluxcd.io/v1beta2\nkind: Kustomization\nmetadata:\nname: age-secrets\nnamespace: flux-system\nannotations:\nsops-public-key/name: sops-age-public-key\nsops-public-key/namespace: flux-system\nspec:\ninterval: 10m\nsourceRef:\nkind: GitRepository\nname: secrets\npath: ./secrets/age\ndecryption:\nprovider: sops\nsecretRef:\nname: sops-age-private-key\nprune: true\nvalidation: server\nNote
This is an essential step in order to allow other operators and developers to utilize WeaveGitOps UI to encrypt SOPS secrets using the public key secret in the cluster.
Tip
In case of using OpenPGP and age in the same cluster, you need to make the kustomizations point to different directories. This is because flux's kustomize-controller expects that all the secrets in the kustomization's path are encrypted with the same key.
"},{"location":"secrets/setup-sops/#bootstrapping-sops-to-leaf-clusters","title":"Bootstrapping SOPS to leaf clusters","text":"Bootstrapping SOPS to leaf clusters in WGE can be done by utilizing ClusterBootstrapConfig job to bootstrap Flux and SOPS. The job is a container which generates SOPS secrets key pair, creates a kubernetes secret with the private key, creates a kubernetes secret with the public key (to be used in self-serve flow) and the proper rbac for it. As well as an option to push the public key to the git repository via a PR (to be distributed).
The following example is using GPG encryption to install SOPS and generate keys when bootstrapping leaf clusters. Create the following ClusterBootstrapConfig CR and push it to your fleet repo.
<CodeBlock title=\"clusters/management/capi/boostrap/sops-bootstrap-job.yaml\" className=\"language-yaml\"
{SopsBootstrapJob}
"},{"location":"secrets/setup-sops/#cluster-template-updates","title":"Cluster template updates","text":"In order to bootstrap SOPS to leaf clusters, we need some modifications to the cluster template to allow creating a Kustomization for reconciling the secrets on the cluster using SOPS and to run the ClusterBootstrapConfig job during cluster creation.
The template metadata should have annotation, it will be used by WGE to create the Kustomization with the cluster files.
templates.weave.works/sops-enabled: \"true\"\nThe template should have the following parameters that are needed for the Kustomization
Expand to view<CodeBlock title=\"clusters/management/capi/templates/template.yaml\" className=\"language-yaml\"
{TemplateParams}
The template should have the following annotations under GitOpsCluster to be used in the bootstrap job
<CodeBlock title=\"clusters/management/capi/templates/template.yaml\" className=\"language-yaml\"
{TemplateAnnotations}
"},{"location":"secrets/setup-sops/#installation-steps","title":"Installation Steps","text":"To bootstrap SOPS on a leaf cluster, create a new cluster using the SOPS template from the Create Cluster page and fill in the following SOPS-related values in the form:
Access to sops decryption secrets should be restricted and allowed only to be read by flux's kustomize controller. This can be done using Kubernetes RBAC.
Here's an example of how you can use RBAC to restrict access to sops decryption secrets:
apiVersion: rbac.authorization.k8s.io/v1\nkind: Role\nmetadata:\nname: sops-secrets-role\nrules:\n- apiGroups: [\"\"]\nresources: [\"secrets\"]\nresourceNames: [\"sops-gpg-private-key\", \"sops-age-private-key\"]\nverbs: [\"get\", \"watch\", \"list\"]\napiVersion: rbac.authorization.k8s.io/v1\nkind: RoleBinding\nmetadata:\nname: sops-secrets-rolebinding\nroleRef:\napiGroup: rbac.authorization.k8s.io\nkind: Role\nname: sops-secrets-role\nsubjects:\n- kind: ServiceAccount\nname: kustomize-controller\nWarning
You would need to ensure that no other rolebindings or clusterrolebndings would allow reading the the decryption secret at any time. This could be achieved by leveraging policy capabilities to detect existing and prevent future creation of roles that would grant read secrets permissions.
"},{"location":"secrets/spec/v1alpha1/secretSync/","title":"SecretSync ENTERPRISE","text":"It provides semantics to sync Kuberentes Secrets from management cluster to leaf clusters.
apiVersion: capi.weave.works/v1alpha1\nkind: SecretSync\nmetadata:\nname: my-dev-secret-syncer\nnamespace: default\nspec:\nclusterSelector:\nmatchLabels:\nenvironment: dev\nsecretRef:\nname: my-dev-secret\ntargetNamespace: my-namespace\nThe documentation for the api version capi.weave.works/v1alpha1
type SecretSync struct {\nmetav1.TypeMeta `json:\",inline\"`\nmetav1.ObjectMeta `json:\"metadata,omitempty\"`\nSpec SecretSyncSpec `json:\"spec,omitempty\"`\nStatus SecretSyncStatus `json:\"status,omitempty\"`\n}\n\n// SecretSyncSpec\ntype SecretSyncSpec struct {\n// Label selector for Clusters. The Clusters that are\n// selected by this will be the ones affected by this SecretSync.\n// It must match the Cluster labels. This field is immutable.\n// Label selector cannot be empty.\nClusterSelector metav1.LabelSelector `json:\"clusterSelector\"`\n// SecretRef specifies the Secret to be bootstrapped to the matched clusters\n// Secret must be in the same namespace of the SecretSync object\nSecretRef v1.LocalObjectReference `json:\"secretRef\"`\n// TargetNamespace specifies the namespace which the secret should be bootstrapped in\n// The default value is the namespace of the referenced secret\n//+optional\nTargetNamespace string `json:\"targetNamespace,omitempty\"`\n}\n\n// SecretSyncStatus secretsync object status\ntype SecretSyncStatus struct {\n// SecretVersions a map contains the ResourceVersion of the secret of each cluster\n// Cluster name is the key and secret's ResourceVersion is the value\nSecretVersions map[string]string `json:\"versions\"`\n}\nTerraform Controller (TF-Controller) is a reliable tool for managing your infrastructure and application resources using the GitOps approach, all at your own pace. An open source project created by Weaveworks, the makers of Flux, TF-Controller follows patterns established by Flux and integrates with Weave GitOps.
TF-Controller makes the following GitOps models available to suit your specific needs:
To get started with TF-controller, simply follow the provided getting started guide. You can also find extensive documentation here\u2014it covers API references, CLI references, and how-to's for common situations.
With Weave GitOps Enterprise, you can manage Terraform objects the same way you can with Kustomization and HelmReleases:
TF-controller has its own versioning system that is separate from the versioning system used by Weave GitOps. This means that you can install and use TF-controller independently of Weave GitOps\u2014it will not be affected by the version of Weave GitOps that you are using.
Here is the dependency matrix:
Version Terraform Source Controller Flux v2 v0.14.0 v1.3.9 v0.35.1 v0.40.x v0.13.1 v1.3.1 v0.31.0 v0.38.x"},{"location":"terraform/get-started-terraform/","title":"Get Started with the Terraform Controller","text":""},{"location":"terraform/get-started-terraform/#preflight-checks","title":"Preflight Checks","text":"To set up the Terraform Controller (TF-Controller), follow the steps in the preflight checks. Here is a summary of what you will need to do:
The exact steps for setting up the TF-controller will depend on the specific environment and infrastructure that you are using. The project's documentation provides additional information to help with setup.
"},{"location":"terraform/get-started-terraform/#setup","title":"Setup","text":"Perform the following actions to set up TF-Controller:
Assuming your username is $GITHUB_USER, you can create a new repository called gitops-tf-controller using the following command:
export GITHUB_USER=<your github username>\nexport GITHUB_TOKEN=<your github personal access token>\n\ngh repo create $GITHUB_USER/gitops-tf-controller\nmkdir -p ./cluster/my-cluster/infra/\nDownload the TF-controller manifest from the release location and save it to ./cluster/my-cluster/infra/tf-controller.yaml\u2014placing the file tf-controller.yaml in this directory:
curl -s https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/release.yaml > ./cluster/my-cluster/infra/tf-controller.yaml\napiVersion: kustomize.config.k8s.io/v1beta1\nkind: Kustomization\nresources:\n- tf-controller.yaml\nAdd the kustomization.yaml file to your Git repository, then push the changes to your repository.
If you want to use TF-Controller with the Notification Controller, you will also need to modify the manifest to enable the two controllers to work together. The exact steps for doing this will depend on the specific requirements of your environment and the configuration of the Notification Controller. You may need to refer to the documentation for the TF-Controller and Notification Controller for more information on how to set this up.
"},{"location":"terraform/get-started-terraform/#other-installation-methods","title":"Other Installation Methods","text":"Before using TF-Controller, you must install Flux by using either flux install or the flux bootstrap command. Make sure you have the latest version of Flux. After that, you can install TF-controller with Flux HelmRelease with this command:
kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/release.yaml\nFor the most recent TF-Controller release candidate, please use rc.yaml:
kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/rc.yaml\nor manually with Helm by:
# Add tf-controller helm repository\nhelm repo add tf-controller https://weaveworks.github.io/tf-controller/\n\n# Install tf-controller\nhelm upgrade -i tf-controller tf-controller/tf-controller \\\n--namespace flux-system\nFor details on configurable parameters of the TF-controller chart, please see this chart Readme.
Alternatively, you can install TF-controller via kubectl:
export TF_CON_VER=v0.14.0\nkubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.crds.yaml\nkubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.rbac.yaml\nkubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.deployment.yaml\nHere's a simple example of how to GitOps your Terraform resources with TF-controller and Flux.
"},{"location":"terraform/get-started-terraform/#define-source","title":"Define Source","text":"First, define a Source controller's source (GitRepository, Bucket, OCIRepository)\u2014for example:
apiVersion: source.toolkit.fluxcd.io/v1beta1\nkind: GitRepository\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\ninterval: 30s\nurl: https://github.com/tf-controller/helloworld\nref:\nbranch: main\nIn this mode, Terraform resources will be planned and automatically applied for you. Enable it by setting .spec.approvePlan=auto:
apiVersion: infra.contrib.fluxcd.io/v1alpha2\nkind: Terraform\nmetadata:\nname: helloworld\nnamespace: flux-system\nspec:\ninterval: 1m\napprovePlan: auto\npath: ./\nsourceRef:\nkind: GitRepository\nname: helloworld\nnamespace: flux-system\nFor a full list of features and how to use them, please visit the Terraform overview.
"},{"location":"terraform/get-started-terraform/#troubleshooting","title":"Troubleshooting","text":""},{"location":"terraform/get-started-terraform/#getting-a-drift-detected-event-message-when-its-a-change-of-source-that-triggered-the-update","title":"Getting adrift detected event message when it's a change of source that triggered the update","text":"Whenever you change a source, you will get a new plan. TF-controller picks up the new plan and applies it. Drift happens if, and only if, the live system changes intentionally. Then TF-controller will generate a lengthy message see an example stating that a drift has occurred. If there is drift, the icon will be red in the TF Objects > Status column of the WGE UI.
"},{"location":"terraform/get-started-terraform/#other-examples","title":"Other Examples","text":"This guide will show you how to use a template to create a Terraform resource in Weave GitOps Enterprise.
"},{"location":"terraform/using-terraform-templates/#cli-guide","title":"CLI Guide","text":""},{"location":"terraform/using-terraform-templates/#prerequisites","title":"Prerequisites","text":"Add the following template to a path in your Git repository that is synced by Flux. For example, in the Installation guide, we set the path that is synced by Flux to ./clusters/management.
Commit and push these changes. Once a template is available in the cluster, it can be used to create a resource, which will be shown in the next step.
Expand to see ./clusters/management/tf-template.yaml ./clusters/management/tf-template.yaml---\napiVersion: clustertemplates.weave.works/v1alpha2\nkind: GitOpsTemplate\nmetadata:\nname: tf-template\nnamespace: default\nspec:\ndescription:\nThis is a sample WGE template that will be translated into a tf-controller specific template.\nparams:\n- name: RESOURCE_NAME\ndescription: Resource Name\nresourcetemplates:\n- content:\n- apiVersion: infra.contrib.fluxcd.io/v1alpha1\nkind: Terraform\nmetadata:\nname: ${RESOURCE_NAME}\nnamespace: flux-system\nspec:\ninterval: 1h\npath: ./\napprovePlan: auto\nalwaysCleanupRunnerPod: true\nsourceRef:\nkind: GitRepository\nname: flux-system\nnamespace: flux-system\nVerify that your template is in the cluster:
kubectl get gitopstemplates.clustertemplates.weave.works -A\nNAME AGE\nsample-wge-tf-controller-template 14m\nIf the template does not appear immediately, reconcile the changes with Flux:
flux reconcile kustomization flux-system\n\u25ba annotating Kustomization flux-system in flux-system namespace\n\u2714 Kustomization annotated\n\u25ce waiting for Kustomization reconciliation\n\u2714 applied revision main/e6f5f0c3925bcfecdb50bceb12af9a87677d2213\nA resource can be created from a template by specifying the template's name and supplying values to it, as well as your Weave GitOps Enterprise username, password, and HTTP API endpoint.
gitops add terraform --from-template sample-wge-tf-controller-template \\\n--set=\"RESOURCE_NAME\"=\"name\" \\\n--username=<username> --password=<password> \\\n--endpoint https://localhost:8000 \\\n--url https://github.com/myawesomeorg/myawesomerepo\n\nCreated pull request: https://github.com/myawesomeorg/myawesomerepo/pull/5\nThis will create a PR in your Git repository with a TF-Controller manifest. Once the PR is merged, TF-Controller will supply the values to the Terraform manifest, apply the Terraform manifest to create the resource, and reconcile any changes that you make to the Terraform manifest!
This template can be used to create multiple resources out of the same Terraform manifest by supplying different values to the template. Any changes to the Terraform manifest will be reconciled automatically to all resources.
"},{"location":"terraform/using-terraform-templates/#3-list-available-templates","title":"3. List available templates","text":"Get a specific template that can be used to create a Terraform resource:
gitops get template terraform sample-wge-tf-controller-template --endpoint https://localhost:8000 --username=<username> --password=<password>\nNAME PROVIDER DESCRIPTION ERROR\nsample-wge-tf-controller-template This is a sample WGE template that will be translated into a tf-controller specific template.\nList all the templates available on the cluster:
gitops get template terraform --endpoint https://localhost:8000 --username=<username> --password=<password>\nNAME PROVIDER DESCRIPTION ERROR\nsample-aurora-tf-template This is a sample Aurora RDS template.\nsample-wge-tf-controller-template This is a sample WGE template that will be translated into a tf-controller specific template.\nList all the parameters that can be defined on a specific template:
gitops get template terraform tf-controller-aurora --list-parameters --endpoint https://localhost:8000 --username=<username> --password=<password>\nNAME REQUIRED DESCRIPTION OPTIONS\nRESOURCE_NAME false Resource Name\nBONUS
For a more advanced example, here is a template to create an Aurora RDS cluster using WGE with Flux and the TF-Controller.
"},{"location":"terraform/using-terraform-templates/#pre-requisites","title":"Pre-requisites","text":"Configure a way to safely store Secrets. One method is to use the Mozilla SOPS CLI, but there are other ways, such as Sealed Secrets or Vaults.
Follow the steps in the Flux docs except for the \"Configure in-cluster secrets decryption\" step! This step looks slightly different for WGE. Instead of re-creating the controllers, you can configure the kustomize-controller as instructed below.
In your Git repository source, add the following to your kustomize-controller configuration:
cat <<EOF >> ./clusters/<cluster-name>/flux-system/gotk-sync.yaml\n decryption:\n provider: sops\n secretRef:\n name: sops-gpg\nEOF\nCreate a Secret to store sensitive values such as the following: - DB username - DB password - AWS Access Key ID - AWS Secret Access Key - AWS Role ARN
Note
If following the Flux guide, this steps corresponds to \"Encrypting secrets using OpenPGP\". You can stop following the Flux guide at this step.
For example, here is what you would do if using the SOPS method:
kubectl -n flux-system create secret generic tf-controller-auth \\\n--from-literal=master_username=admin \\\n--from-literal=master_password=change-me \\\n--from-literal=aws_access_key=AKIAIOSFODNN7EXAMPLE \\\n--from-literal=aws_secret_key=\"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\" \\\n--from-literal=aws_role_arn=\"arn:aws:iam::012345678910:role/wge-tf-controller-example\" \\\n--dry-run=client \\\n-o yaml > tf-controller-auth.yaml\nThen, encrypt the secret:
sops --encrypt --in-place tf-controller-auth.yaml\nCommit and push your changes. You can now store encrypted secrets to your Git repository.
"},{"location":"terraform/using-terraform-templates/#4-add-the-manifests-to-your-cluster","title":"4. Add the manifests to your cluster","text":"Add the following Terraform manifest to the root of your Git repository.
Expand to see Terraform manifest ./rds.tfterraform {\nrequired_providers {\naws = {\nsource = \"hashicorp/aws\"\nversion = \"~> 3.0\"\n}\n}\n}\n\nvariable \"cluster_identifier\" {}\nvariable \"database_name\" {}\nvariable \"master_username\" {}\nvariable \"master_password\" {}\nvariable \"backup_retention_period\" {}\nvariable \"region\" {}\nvariable \"aws_access_key\" {}\nvariable \"aws_secret_key\" {}\nvariable \"aws_role_arn\" {}\n\nprovider \"aws\" {\nregion = var.region\naccess_key = var.aws_access_key\nsecret_key = var.aws_secret_key\n\nassume_role {\nrole_arn = var.aws_role_arn\n}\n}\n\nlocals {\nengine = \"aurora-mysql\"\nengine_version = \"5.7.mysql_aurora.2.07.5\"\nport = 3306\n}\n\ndata \"aws_availability_zones\" \"available\" {\nstate = \"available\"\n\nfilter {\nname = \"group-name\"\nvalues = [var.region]\n}\n}\n\nresource \"aws_rds_cluster\" \"mycluster\" {\ncluster_identifier = var.cluster_identifier\nengine = local.engine\nengine_version = local.engine_version\nport = local.port\navailability_zones = slice(data.aws_availability_zones.available.names, 0, 3)\ndatabase_name = var.database_name\nmaster_username = var.master_username\nmaster_password = var.master_password\nbackup_retention_period = var.backup_retention_period\nskip_final_snapshot = true\napply_immediately = true\n}\n\nresource \"aws_rds_cluster_instance\" \"cluster_instance\" {\ncount = 1\nidentifier = \"${aws_rds_cluster.mycluster.id}-${count.index}\"\ncluster_identifier = aws_rds_cluster.mycluster.id\ninstance_class = \"db.t3.small\"\nengine = aws_rds_cluster.mycluster.engine\nengine_version = aws_rds_cluster.mycluster.engine_version\n}\nAdd the following template to a path in your Git repository that is synced by Flux. In the quickstart guide, we set this path to ./clusters/management.
---\napiVersion: clustertemplates.weave.works/v1alpha2\nkind: GitOpsTemplate\nmetadata:\nname: rds-template\nnamespace: default\nspec:\ndescription: This is a sample Aurora RDS template.\nparams:\n- name: RESOURCE_NAME\ndescription: Resource Name\n- name: CLUSTER_IDENTIFIER\ndescription: Cluster Identifier\n- name: DATABASE_NAME\ndescription: Database Name\n- name: BACKUP_RETENTION_PERIOD\ndescription: Backup Retention Period\n- name: REGION\ndescription: Region\nresourcetemplates:\n- contents:\n- apiVersion: infra.contrib.fluxcd.io/v1alpha1\nkind: Terraform\nmetadata:\nname: ${RESOURCE_NAME}\nnamespace: flux-system\nspec:\ninterval: 1h\npath: ./\napprovePlan: auto\nalwaysCleanupRunnerPod: true\nvars:\n- name: cluster_identifier\nvalue: ${CLUSTER_IDENTIFIER}\n- name: database_name\nvalue: ${DATABASE_NAME}\n- name: backup_retention_period\nvalue: ${BACKUP_RETENTION_PERIOD}\n- name: region\nvalue: ${REGION}\nvarsFrom:\n- kind: Secret\nname: tf-controller-auth\nsourceRef:\nkind: GitRepository\nname: flux-system\nnamespace: flux-system\nCommit and push your changes.
Tip
You can change the location where you keep your Terraform manifests in your Git source (which the TF-Controller will reconcile) by configuring spec.resourcetemplates.spec.path.
gitops add terraform --from-template rds-template \\\n--username=<username> --password=<password> \\\n--endpoint https://localhost:8000 \\\n--url https://github.com/myawesomeorg/myawesomerepo \\\n--set \"RESOURCE_NAME\"=\"tf-controller-aurora\",\"CLUSTER_IDENTIFIER\"=\"super-awesome-aurora\",\"DATABASE_NAME\"=\"db1\",\"BACKUP_RETENTION_PERIOD\"=5,\"REGION\"=\"us-west-2\"\n\nCreated pull request: https://github.com/myawesomeorg/myawesomerepo/pull/6\nMerge the PR in your Git repository to add the TF-Controller manifest. TF-Controller will supply the values to the Terraform manifest, apply the Terraform manifest to create the resource, and reconcile any changes that you make to the Terraform manifest.
Any changes to your Terraform manifest will be automatically reconciled by the TF-controller with Flux.
You can re-use this template to create multiple Terraform resources, each with a different set of values!
Make sure to delete the newly created RDS resources to not incur additional costs.
"},{"location":"workspaces/","title":"Introduction ENTERPRISE","text":""},{"location":"workspaces/#workspaces","title":"Workspaces","text":"Organizations working with Kubernetes have a tremendous need to manage tenancy for numerous software delivery teams. Weave GitOps Workspaces offers tenancy management for Kubernetes clusters at scale. It\u2019s built on top of Flux's powerful approach to managing tenancy, and adds policies that will help you to define finer-grain rules on your tenants.
With WGE Workspaces, all it takes for platform operators to create workspaces is a single CLI command that generates:
Multi tenancy provides users with the ability to define boundaries to multiple engineering teams working on a single cluster. Through a simple interface it adds permissions to the necessary Kubernetes resources to make it easy for customers to manage their multiple tenants.
WGE multi tenancy expands on the multi tenancy feature provided by flux. In addition to creating the necessary Kubernetes tenancy resources that flux adds, multi tenancy in WGE also adds the following: - Defining tenancy using a single yaml file that serves as a source of truth for the organization - Makes use of WGE policy features to enforce non Kubernetes native permissions
gitops command line tool is responsible for creating the multi tenancy resources. The tool is distributed as part of WGE offering. It reads the definitions of a yaml file and can either apply the necessary changes directly to the cluster or output it to stdout so it can be saved into a file and pushed to a repo to be reconciled by flux.
To make use of the policy features, policy agent needs to be installed in the necessary cluster(s).
"},{"location":"workspaces/multi-tenancy/#tenancy-file","title":"Tenancy file","text":"Below is an example of a tenancy file:
Expand to view tenancy.yaml---\ntenants:\n- name: first-tenant\nnamespaces:\n- first-ns\n- name: second-tenant\nnamespaces:\n- second-test-ns\n- second-dev-ns\nallowedRepositories:\n- kind: GitRepository\nurl: https://github.com/testorg/testrepo\n- kind: GitRepository\nurl: https://github.com/testorg/testinfo\n- kind: Bucket\nurl: minio.example.com\n- kind: HelmRepository\nurl: https://testorg.github.io/testrepo\nallowedClusters:\n- kubeConfig: cluster-1-kubeconfig\n- kubeConfig: cluster-2-kubeconfig\nteamRBAC:\ngroupNames:\n- foo-group\n- bar-group\nrules:\n- apiGroups:\n- ''\nresources:\n- 'namespaces'\n- 'pods'\nverbs:\n- 'list'\n- 'get'\ndeploymentRBAC:\nbindRoles:\n- name: foo-role\nkind: Role\nrules:\n- apiGroups:\n- ''\nresources:\n- 'namespaces'\n- 'pods'\nverbs:\n- 'list'\n- 'get'\nserviceAccount:\nname: \"reconcilerServiceAccount\"\nThe file above defines two tenants: first-tenant and second-tenant as follows:
Global options:
The command creates the necessary resources to apply multi tenancy on the user's cluster. To use the command to apply the resources directly the user needs to have the necessary configuration to connect to the desired cluster. The command considers the tenancy file as a source of truth and will change the cluster state to match what is currently described in the file.
For more control on a specific tenant a tenancy file should be used, the command allows the creation of the base resources that defines a tenancy through the arguments:
gitops create tenants --name test-tenant --namespace test-ns1 --namespace test-ns2\nnamespace/test-ns1 created\ntest-ns1/serviceaccount/test-tenant created\ntest-ns1/rolebinding.rbac.authorization.k8s.io/test-tenant-service-account-cluster-admin created\nnamespace/test-ns2 created\ntest-ns2/serviceaccount/test-tenant created\ntest-ns2/rolebinding.rbac.authorization.k8s.io/test-tenant-service-account-cluster-admin created\npolicy.pac.weave.works/weave.policies.tenancy.test-tenant-allowed-application-deploy created\nThe above will create the namespaces and permissions through a ServiceAccount with the same name as the tenant, test-tenant in the case of the above example, in each required namespace. The same can be done through a file as follows:
tenants:\n- name: test-tenant\nnamespaces:\n- test-ns1\n- test-ns2\ngitops create tenants --from-file tenants.yaml\nnamespace/test-ns1 created\ntest-ns1/serviceaccount/test-tenant created\ntest-ns1/rolebinding.rbac.authorization.k8s.io/test-tenant-service-account-cluster-admin created\nnamespace/test-ns2 created\ntest-ns2/serviceaccount/test-tenant created\ntest-ns2/rolebinding.rbac.authorization.k8s.io/test-tenant-service-account-cluster-admin created\npolicy.pac.weave.works/weave.policies.tenancy.test-tenant-allowed-application-deploy created\nTo check the resources that would be deployed first use the export flag:
gitops create tenants --from-file tenants.yaml --export\napiVersion: v1\nkind: Namespace\nmetadata:\ncreationTimestamp: null\nlabels:\n toolkit.fluxcd.io/tenant: test-tenant\nname: test-ns1\nspec: {}\nstatus: {}\n---\napiVersion: v1\nkind: ServiceAccount\nmetadata:\ncreationTimestamp: null\nlabels:\n toolkit.fluxcd.io/tenant: test-tenant\nname: test-tenant\nnamespace: test-ns1\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: RoleBinding\nmetadata:\ncreationTimestamp: null\nlabels:\n toolkit.fluxcd.io/tenant: test-tenant\nname: test-tenant-service-account-cluster-admin\nnamespace: test-ns1\nroleRef:\napiGroup: rbac.authorization.k8s.io\nkind: ClusterRole\nname: cluster-admin\nsubjects:\n- kind: ServiceAccount\nname: test-tenant\nnamespace: test-ns1\n---\napiVersion: v1\nkind: Namespace\nmetadata:\ncreationTimestamp: null\nlabels:\n toolkit.fluxcd.io/tenant: test-tenant\nname: test-ns2\nspec: {}\nstatus: {}\n---\napiVersion: v1\nkind: ServiceAccount\nmetadata:\ncreationTimestamp: null\nlabels:\n toolkit.fluxcd.io/tenant: test-tenant\nname: test-tenant\nnamespace: test-ns2\n---\napiVersion: rbac.authorization.k8s.io/v1\nkind: RoleBinding\nmetadata:\ncreationTimestamp: null\nlabels:\n toolkit.fluxcd.io/tenant: test-tenant\nname: test-tenant-service-account-cluster-admin\nnamespace: test-ns2\nroleRef:\napiGroup: rbac.authorization.k8s.io\nkind: ClusterRole\nname: cluster-admin\nsubjects:\n- kind: ServiceAccount\nname: test-tenant\nnamespace: test-ns2\n---\napiVersion: pac.weave.works/v2beta2\nkind: Policy\nmetadata:\ncreationTimestamp: null\nlabels:\n toolkit.fluxcd.io/tenant: test-tenant\nname: weave.policies.tenancy.test-tenant-allowed-application-deploy\nspec:\ncategory: weave.categories.tenancy\ncode: |\npackage weave.tenancy.allowed_application_deploy\n\n controller_input := input.review.object\n violation[result] {\nnamespaces := input.parameters.namespaces\n targetNamespace := controller_input.spec.targetNamespace\n not contains_array(targetNamespace, namespaces)\nresult = {\n\"issue detected\": true,\n \"msg\": sprintf(\"using target namespace %v is not allowed\", [targetNamespace]),\n }\n}\nviolation[result] {\nserviceAccountName := controller_input.spec.serviceAccountName\n serviceAccountName != input.parameters.service_account_name\n result = {\n\"issue detected\": true,\n \"msg\": sprintf(\"using service account name %v is not allowed\", [serviceAccountName]),\n }\n}\ncontains_array(item, items) {\nitems[_] = item\n }\ndescription: Determines which helm release and kustomization can be used in a tenant\nhow_to_solve: \"\"\nid: weave.policies.tenancy.test-tenant-allowed-application-deploy\nname: test-tenant allowed application deploy\nparameters:\n- name: namespaces\n required: false\ntype: array\n value:\n - test-ns1\n - test-ns2\n- name: service_account_name\n required: false\ntype: string\n value: test-tenant\nprovider: kubernetes\nseverity: high\nstandards: []\ntags:\n- tenancy\ntargets:\n kinds:\n - HelmRelease\n - Kustomization\n labels: []\nnamespaces:\n - test-ns1\n - test-ns2\nstatus: {}\n---\nApplying the resources through the command line is not usually recommended. For WGE the recommended way is to commit the result of the create tenants command to source control and let flux handle deployment. To achieve that you can save the result of the export to a file:
gitops create tenants --from-file tenants.yaml --export > clusters/management/tenants.yaml From the side menu, you can click on the Workspaces tab to go to the workspaces list view.
This view lists workspaces across all clusters. You can filter workspaces by their clusters or their names.
"},{"location":"workspaces/view-workspaces/#workspace-details-view","title":"Workspace Details View","text":"You can go to this view by clicking on the name of the workspace in the Workspaces List View.
In this view you can see all details of the workspace such as its name, namespace, and all resources related to this workspace.
"}]} \ No newline at end of file diff --git a/userdocs/site/secrets/assets/sops-bootstrap-job.yaml b/userdocs/site/secrets/assets/sops-bootstrap-job.yaml new file mode 100644 index 0000000000..255b9525d1 --- /dev/null +++ b/userdocs/site/secrets/assets/sops-bootstrap-job.yaml @@ -0,0 +1,68 @@ +apiVersion: capi.weave.works/v1alpha1 +kind: ClusterBootstrapConfig +metadata: + name: sops-installation + namespace: default +spec: + clusterSelector: + matchLabels: + weave.works/flux: "bootstrap" + jobTemplate: + generateName: "run-gitops-flux-{{ .ObjectMeta.Name }}" + spec: + containers: + - image: ghcr.io/fluxcd/flux-cli:v0.35.0 + imagePullPolicy: Always + name: flux-bootstrap + resources: {} + volumeMounts: + - name: kubeconfig + mountPath: "/etc/gitops" + readOnly: true + args: + [ + "bootstrap", + "github", + "--kubeconfig=/etc/gitops/value", + "--owner=Bootstrapping Secrets ENTERPRISE¶
When accessing protected resources there is a need for a client to authenticate before the access is granted and the resource is consumed. For authentication, a client presents credentials that are either created manually or available through infrastructure. A common scenario is to have a secrets store.
Weave Gitops allows you to provision the secret management infrastructure as part of its capabilities. However, in order to provision, as any other application that has secrets, we need to create the secret needed for installing it. This is known as a chicken-egg scenario that get addressed by providing an initial secret. This secret we call it bootstrapping secret.
Bootstrapping secrets comes in handy, not only while provisioning your secrets management solution, but also in any platform provisioning task where the existence of the secret is a prerequisite. Another common example could be provisioning platform capabilities via profiles that are stored in private repositories.
Weave Gitops provides SecretSync as a solution to managing your bootstrapping secrets.
SecretSync¶
Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
SecretSync is a Kubernetes Custom Resource that provides semantics to sync Kuberentes Secrets from management cluster to leaf clusters.
An example could be seen below:
apiVersion: capi.weave.works/v1alpha1
+kind: SecretSync
+metadata:
+ name: my-dev-secret-syncer
+ namespace: default
+spec:
+ clusterSelector:
+ matchLabels:
+ environment: dev
+ secretRef:
+ name: my-dev-secret
+ targetNamespace: my-namespace
+1) Select the secret to sync:
secretRef:
+ name: my-dev-secret
+2) Specify the GitopsClusters that the secret will be synced to via labels:
clusterSelector:
+ matchLabels:
+ environment: dev
+Secretsync reconciles secrets on clusters: any cluster at a future time matching the label selector will have the secret reconciled too.
More info about the CRD spec here
Working with SecretSync¶
Pre-requisites¶
Expand to see example
apiVersion: gitops.weave.works/v1alpha1
+kind: GitopsCluster
+metadata:
+namespace: flux-system
+labels:
+ environment: dev
+Expand to see example
apiVersion: v1
+kind: Secret
+metadata:
+name: my-dev-secret
+namespace: flux-system
+type: Opaque
+Info
Some restriction apply to the current version: - Resources should be in the same namespace - Leaf cluster nodes should be annotated with node-role.kubernetes.io/control-plane
Syncing secrets via SecretSync¶
apiVersion: capi.weave.works/v1alpha1
+kind: SecretSync
+metadata:
+ name: my-dev-secret-syncer
+ namespace: default
+spec:
+ clusterSelector:
+ matchLabels:
+ environment: dev
+ secretRef:
+ name: my-dev-secret
+ targetNamespace: my-namespace
+Once reconciled, the status section would show created secret resource version
status:
+ versions:
+ leaf-cluster-1: "211496"
+Your secret has been created in the target leaf cluster
➜ kubectl get secret -n default
+NAME TYPE DATA
+my-dev-secret Opaque 1
+Getting started with secrets management ENTERPRISE¶
Warning
This feature is in alpha and certain aspects will change We're very excited for people to use this feature. However, please note that changes in the API, behaviour and security will evolve. The feature is suitable to use in controlled testing environments.
This guide shows you a basic experience to get started with Weave Gitops Secrets. It covers the scenario of setting up the capability in a test environment and how to use it for your applications.
Requirements¶
Add the secrets infra¶
In order to be able to manage external secrets stores and secrets, add external-secrets application from weaveworks-charts profiles repository.
Include via values.yaml the configuration to deploy the SecretStore connecting to AWS Secrets Manager.
values:
+ secretStores:
+ enabled: true
+ path: ./clusters/bases/secrets
+ sourceRef:
+ kind: GitRepository
+ name: flux-system
+ namespace: flux-system
+clusters/bases/secrets in our configuration repo where a kustomization exists apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+- aws-secrets-manager.yaml
+With the AWS Secrets Manager secret store
apiVersion: external-secrets.io/v1beta1
+kind: SecretStore
+metadata:
+ name: aws-secrets-manager
+ namespace: flux-system
+spec:
+ provider:
+ aws:
+ auth:
+ secretRef:
+ accessKeyIDSecretRef:
+ key: access-key
+ name: awssm-secret
+ secretAccessKeySecretRef:
+ key: secret-access-key
+ name: awssm-secret
+ region: eu-north-1
+ service: SecretsManager
+Review and merge the PR and see it available in your cluster
Create the secret¶
Given you have a secret in AWS Secrets Manager for example test/search/db.
Create the External Secret manifest via Secrets UI to pull the secret from your store into your environment.
See it available in your cluster.
Use the secret¶
At this stage you have everything you need for your application to consume the secret. Add it to your application as usual.
Expand to see example
apiVersion: v1
+kind: Pod
+metadata:
+name: secret-dotfiles-pod
+spec:
+volumes:
+- name: database-secrets
+ secret:
+ secretName: search-database
+containers:
+- name: dotfile-test-container
+ image: registry.k8s.io/busybox
+ command:
+ - ls
+ - "-l"
+ - "/etc/database-secrets"
+ volumeMounts:
+ - name: database-secrets
+ readOnly: true
+ mountPath: "/etc/database-secrets"
+You could see the expected secret available
kubectl logs -f secret-dotfiles-pod
+
+total 0
+lrwxrwxrwx 1 root root 15 Apr 5 17:26 password -> ..data/password
+Next steps?¶
Overview ENTERPRISE¶
Secrets Management¶
Secrets are sensitive information such as passwords, access keys, and other credentials that should not be exposed publicly. In cloud-native applications, secrets are often used to authenticate and authorize access to various resources, such as databases, APIs, and other services.
In a GitOps environment, secrets are typically stored either encrypted in Git, or using Custom Resources that reference the secret in an external secret store. Secrets are then synced into the clusters and securely passed to the application containers or workloads.
Effective secrets management in cloud-native applications and GitOps environments is critical for maintaining the security and compliance of the overall system. Best practices include regularly rotating secrets, using strong encryption and access controls, and implementing robust auditing and monitoring processes.
Weave Gitops Secrets Management¶
Weave GitOps Secrets Management is a set of features that makes it easier for teams to manage secrets in a GitOps environment across multiple clusers. These features provide an automated way to manage secrets effectively, and make it easier for different personas to work with secrets.
For Developers, they can use Weave GitOps Secrets Management to securely create and track application secrets such as API keys, passwords, and other credentials. They can do that using Weave GitOps UI in a self-serve manner.
For Operation Teams, they can use Weave GitOps Secrets Management to help set up secure and reliable flows for developers to create and consume secrets for their applications.
Weave GitOps Secrets Management supports integrations with SOPS and External Secrets Operator (ESO) to provide a secure and automated way to manage secrets in a GitOps environment, while giving the option for customers to choose any of these secrets operators or working with both of them.
For SOPS and ESO operators, Weave GitOps is providing different ways to do the following: * Setup Secrets Operators (SOPS | ESO) * Bootstrap Secrets into clusters * Manage Secrets through Weave GitOps UI
In order to get started with WeaveGitOps Secrets Management, please follow this guide here.
Manage Secrets UI ENTERPRISE¶
At Weave GitOps Enterprise (WGE), we support two approaches for creating and managing secrets: External Secrets Operator and Mozilla SOPS. In this guide, we will provide an overview of both approaches and explain how to use the UI to create and manage secrets.
Clicking on the Secrets under the Platform section in the left hand menu will bring you to the secrets page where you can create external secrets, sops secrets, and view the external secrets list.
External Secrets¶
Prerequisites¶
Setup the External Secrets Operator by following this guide.
Create External Secret CR¶
To create a new ExternalSecret CR, start by clicking on to the Create External Secret button to navigate to the creation page.
Here, you will be prompted to enter the External Secret Name and the Target K8s Secret Name. Once you choose the Target Cluster, you will find a new list of all the Secret Stores on this cluster to choose from.
It's important to note that the chosen SecretStore may be a cluster-scoped SecretStore ie: ClusterSecretStore or a namespace-scoped SecretStore.
If you choose a namespace scoped SecretStore, the new secret will be created on the same namespace as the SecretStore.
If you choose a cluster-scoped ClusterSecretStore, the new secret will be created in a namespace of your choice.
Then you need to add the SecretPath, which is the path to the external secret within the secret store.
Adding Secret Properties¶
After you have chosen your desired SecretStore & SecretPath the UI allows you to add secret properties in two differen scenarios:
1. Adding specific properties¶
The first scenario allows you to add specific property fields. Each added property also has an optional SecretKey field. Here's how to do it:
In the Properties section, click the Add button to create a new property field.
Enter the name of the property you want to create. You can add as many properties as you need.
If you wish to specify a SecretKey for the property, enter it in the SecretKey field. If this field is left blank, the property name will be used as the SecretKey.
To remove a property, click the Remove sign next to the property you wish to delete.
Remember, this option allows you to have fine-grained control over which properties are included in your ExternalSecret.
2. Including All Properties¶
The second scenario is to include all properties in your ExternalSecret. If the Include all properties checkbox is checked, all property inputs will be disabled and ignored, and all secrets including all keys under the specified SecretPath will be added. Here's how:
Check the Include all properties checkbox. This will automatically disable the property input fields.
Using this option allows you to quickly create an ExternalSecret that includes all secrets under a specific SecretPath, without the need to specify each one individually.
Warning
Remember to use this option with caution. You may not need to expose all your secret properties to be on the cluster.
This process allows you to easily create new ExternalSecret CRs without needing to manually create them through YAML files or command line tools.
List External Secrets¶
The ExternalSecrets List section of the UI allows you to view all the external secrets that are currently stored in your Kubernetes clusters. This section provides an overview of each external secret, including its name, namespace, cluster, k8s-secret, secret-store and the age. From this page, you can also navigate to the details page to view more information about a specific secret.
External Secret Details¶
The details page displays the details of a specific external secret, including its name, namespace, data, and creation date. Below are the details that you can expect to see on this page:
Based on the configuration of the external secret, this section will vary:
Understanding the information provided on the details page can help you to manage and troubleshoot your external secrets as needed.
Understanding Events¶
The following events can be expected when using the UI to manage external secrets:
Understanding these events can help you to troubleshoot issues that may arise when managing external secrets using the UI. In particular, if you encounter a Not Ready event, you may need to check your secret store credentials and ensure that the secret store is operational before proceeding with any further actions.
SOPS¶
Getting Started with SOPS¶
Creating a SOPS secret involves using the SOPS tool to encrypt a file containing sensitive information, such as credentials or API keys. This encrypted file can then be stored securely in version control or another location, with only authorized users able to decrypt it using their own private key. This adds an additional layer of security to sensitive data, reducing the risk of unauthorized access or accidental exposure.
Prerequisites¶
For more information about how to generate OpenPGP/age keys and configure your cluster to work with Weave GitOps Enterprise secrets management follow this guide.
Create SOPS Secret¶
To create a new SOPS secret, start by clicking on the Create Sops Secret button.
This will open the create form where you can specify the details of your new secret. First, choose the Cluster where you want to create the secret. Then, enter a name for your secret and select the namespace where it will be created.
Next, select the encryption method that you want to use - currently, only GPG/AGE encryption is supported. Finally, choose the kustomization that will be used by SOPS to decrypt the secret, as well as, having the public key info that will be used to encrypt the secret data. Afterwards, add your key-value pairs of your secrets. It's important to note that the value input will be encoded to base64.
The generated secret should be something like below.
After approving the pull request, Flux will reconcile it to your cluster. To verify that the secret has been successfully created, you can use the following command to retrieve it as YAML:
kubectl get secret secretTest-default-sops-secret -n default -o yaml
+which will give the following output:
apiVersion: v1
+data:
+ secret-1: dmFsCg==
+kind: Secret
+metadata:
+ name: secretTest-default-sops-secret
+ namespace: default
+type: Opaque
+Setup ESO ENTERPRISE¶
Weave GitOps Enterprise now supports managing secrets using External Secrets Operator from the UI. External Secrets Operator is a Kubernetes operator that allows users to use secrets from external secrets management systems by reading their information using external APIs and injecting their values into Kubernetes secrets. To be able to use this functionality, users need to configure their External Secrets Operator and SecretStores using one of the guides below.
Prerequisites¶
SecretStores¶
You should have your SecretStore CRs defined in a git repository. Those CRs will be installed to your cluster in the following steps and used by the creation UI.
ESO Profile¶
The ESO profile is packaged with the weaveworks-charts. If you have the usual profiles setup, you will not need to do anything extra. This profile installs the ESO controller, all the required CRDs, and the SecretStore CRs defined in the previous step.
Secrets¶
There are several Kubernetes Secrets that need to exist on your management cluster for the whole flow to work.
If your SecretStores repository is private then you'll need a Secret, that contains the repo credentials, to access the repository. This is usually the Secret you created while bootstrapping Flux on the management cluster and is copied to your leaf cluster during creation.
For each SecretStore CR, you'll need to add a Secret, that follows the format expected by this CR, to allow the operator to access the defined External Secret Store.
Follow this guide for bootstrapping those secrets on leaf clusters.
Installation Steps¶
Install ESO on management cluster or existing leaf cluster¶
To install the ESO profile on an exisitng cluster, use Add an application from the Applications page and select external-secrets from weaveworks-charts. Check the Profile values section for more info about configuring the values.yaml.
Install ESO on leaf cluster¶
To bootstrap the ESO profile on a leaf cluster, select external-secrets from the profiles dropdown in the Create Cluster page. Check the Profile values section for more info about configuring the values.yaml.
Profile values¶
You should then configure the values.yaml to install the SecretStores on the cluster from a GitRepository. This is done by configuring the secretStores section.
Expand to see an example that creates a new git source from a specific tag
secretStores:
+enabled: true
+url: ssh://git@github.com/github-owner/repo-name # url for the git repository that contains the SecretStores
+tag: v1.0.0
+path: ./ # could be a path to the secrets dir or a kustomization.yaml file for the SecretStore in the GitRepository
+secretRef: my-pat # the name of the Secret containing the repo credentials for private repositories
+Expand to see an example that uses an existing git source
secretStores:
+enabled: true
+sourceRef: # Specify the name for an existing GitSource reference
+ kind: GitRepository
+ name: flux-system
+ namespace: flux-system
+import CodeBlock from "@theme/CodeBlock";
import SopsBootstrapJob from "!!raw-loader!./assets/sops-bootstrap-job.yaml"; import TemplateParams from "!!raw-loader!./assets/template-params.yaml"; import TemplateAnnotations from "!!raw-loader!./assets/template-annotations.yaml";
Setup SOPS ENTERPRISE¶
Weave GitOps Enterprise now supports managing secrets using SOPS, a tool that encrypts and decrypts secrets using various key management services, from the UI. To be able to use this functionality, users need to configure their private and public key-pairs using one of the guides below.
Setup SOPS on management cluster or existing leaf cluster¶
In this section, we will cover the prerequisites for using SOPS with Weave GitOps Enterprise, and how to configure SOPS for your existing Kubernetes cluster to work with GPG and age keys.
For a more advanced setup for SOPS with flux, please refer to this guide.
Encrypting secrets using GPG/OpenPGP¶
OpenPGP is a way of using SOPS to encrypt and decrypt secrets with Weave GitOps Enterprise.
Here are the steps to generate an OpenPGP key and configure your cluster to work with Weave GitOps Enterprise secrets management.
1- Generate a gpg key pairs
Expand for instructions
export KEY_NAME="gpg-key"
+export KEY_COMMENT="gpg key"
+
+gpg --batch --full-generate-key <<EOF
+%no-protection
+Key-Type: 1
+Key-Length: 4096
+Subkey-Type: 1
+Subkey-Length: 4096
+Expire-Date: 0
+Name-Comment: ${KEY_COMMENT}
+Name-Real: ${KEY_NAME}
+EOF
+2- Export the key pairs fingerprint in the shell
gpg --list-secret-keys "${KEY_NAME}"
+
+sec rsa4096 2020-09-06 [SC]
+ 710DC0DB6C1662F707095FC30233CB21E656A3CB
+
+export KEY_FP="710DC0DB6C1662F707095FC30233CB21E656A3CB"
+3- Export the generated private key to a kubernetes secret sops-gpg-private-key which will be used by flux's kustomize-controller to decrypt the secrets using sops.
gpg --export-secret-keys --armor "${KEY_FP}" |
+kubectl create secret generic sops-gpg-private-key \
+--namespace=flux-system \
+--from-file=sops.asc=/dev/stdin
+4- Export the generated public key to a kubernetes secret sops-gpg-public-key which will be used by Weave GitOps Enterprise to encrypt the secrets created from the UI.
gpg --export --armor "${KEY_FP}" |
+kubectl create secret generic sops-gpg-public-key \
+--namespace=flux-system \
+--from-file=sops.asc=/dev/stdin
+Tip
It's recommended to remove the secret from your machine
gpg --delete-secret-keys "${KEY_FP}"
+5- Create a kustomization for reconciling the secrets on the cluster and set the --decryption-secret flag to the name of the private key created in step 3.
flux create kustomization gpg-secrets \
+--source=secrets \ # the git source to reconcile the secrets from
+--path=./secrets/gpg \
+--prune=true \
+--interval=10m \
+--decryption-provider=sops \
+--decryption-secret=sops-gpg-private-key
+6- Annotate the kustomization object created in the previous step with the name and namespace of the public key created in step 4.
kubectl annotate kustomization gpg-secrets \
+sops-public-key/name=sops-gpg-public-key \
+sops-public-key/namespace=flux-system \
+-n flux-system
+Expand to see the expected kustomization object
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+kind: Kustomization
+metadata:
+name: gpg-secrets
+namespace: flux-system
+annotations:
+ sops-public-key/name: sops-gpg-public-key
+ sops-public-key/namespace: flux-system
+spec:
+interval: 10m
+sourceRef:
+ kind: GitRepository
+ name: secrets
+path: ./secrets/gpg
+decryption:
+ provider: sops
+ secretRef:
+ name: sops-gpg-private-key
+prune: true
+validation: server
+Note
This is an essential step in order to allow other operators and developers to utilize WeaveGitOps UI to encrypt SOPS secrets using the public key secret in the cluster.
Encrypting secrets using age¶
age is a simple, modern and secure file encryption tool, that can be used to encrypt secrets using Weave GitOps Enterprise.
Here are the steps to generate an age key and configure your cluster to work with Weave GitOps Enterprise secrets management.
1- Generate an age key with age-keygen
age-keygen -o age.agekey
+
+Public key: <public key>
+2- Export the generated private key to a kubernetes secret sops-age-private-key which will be used by flux's kustomize-controller to decrypt the secrets using sops.
cat age.agekey |
+kubectl create secret generic sops-age-private-key \
+--namespace=flux-system \
+--from-file=age.agekey=/dev/stdin
+4- Export the generated public key to a kubernetes secret sops-age-public-key which will be used by Weave GitOps Enterprise to encrypt the secrets created from the UI.
echo "<public key>" |
+kubectl create secret generic sops-age-public-key \
+--namespace=flux-system \
+--from-file=age.agekey=/dev/stdin
+Tip
It's recommended to remove the secret from your machine
rm -f age.ageKey
+5- Create a kustomization for reconciling the secrets on the cluster and set the --decryption-secret flag to the name of the private key created in step 2.
flux create kustomization age-secrets \
+--source=secrets \ # the git source to reconcile the secrets from
+--path=./secrets/age \
+--prune=true \
+--interval=10m \
+--decryption-provider=sops \
+--decryption-secret=sops-age-private-key
+6- Annotate the kustomization object created in the previous step with the name and namespace of the public key created in step 4.
kubectl annotate kustomization age-secrets \
+sops-public-key/name=sops-age-public-key \
+sops-public-key/namespace=flux-system \
+-n flux-system
+Expand to see the expected kustomization object
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+kind: Kustomization
+metadata:
+name: age-secrets
+namespace: flux-system
+annotations:
+ sops-public-key/name: sops-age-public-key
+ sops-public-key/namespace: flux-system
+spec:
+interval: 10m
+sourceRef:
+ kind: GitRepository
+ name: secrets
+path: ./secrets/age
+decryption:
+ provider: sops
+ secretRef:
+ name: sops-age-private-key
+prune: true
+validation: server
+Note
This is an essential step in order to allow other operators and developers to utilize WeaveGitOps UI to encrypt SOPS secrets using the public key secret in the cluster.
Tip
In case of using OpenPGP and age in the same cluster, you need to make the kustomizations point to different directories. This is because flux's kustomize-controller expects that all the secrets in the kustomization's path are encrypted with the same key.
Bootstrapping SOPS to leaf clusters¶
Bootstrapping SOPS to leaf clusters in WGE can be done by utilizing ClusterBootstrapConfig job to bootstrap Flux and SOPS. The job is a container which generates SOPS secrets key pair, creates a kubernetes secret with the private key, creates a kubernetes secret with the public key (to be used in self-serve flow) and the proper rbac for it. As well as an option to push the public key to the git repository via a PR (to be distributed).
Prerequisites¶
ClusterBootstrapConfig job¶
The following example is using GPG encryption to install SOPS and generate keys when bootstrapping leaf clusters. Create the following ClusterBootstrapConfig CR and push it to your fleet repo.
Expand to view
<CodeBlock title="clusters/management/capi/boostrap/sops-bootstrap-job.yaml" className="language-yaml"
{SopsBootstrapJob}
Cluster template updates¶
In order to bootstrap SOPS to leaf clusters, we need some modifications to the cluster template to allow creating a Kustomization for reconciling the secrets on the cluster using SOPS and to run the ClusterBootstrapConfig job during cluster creation.
The template metadata should have annotation, it will be used by WGE to create the Kustomization with the cluster files.
templates.weave.works/sops-enabled: "true"
+The template should have the following parameters that are needed for the Kustomization
Expand to view
<CodeBlock title="clusters/management/capi/templates/template.yaml" className="language-yaml"
{TemplateParams}
The template should have the following annotations under GitOpsCluster to be used in the bootstrap job
Expand to view
<CodeBlock title="clusters/management/capi/templates/template.yaml" className="language-yaml"
{TemplateAnnotations}
Installation Steps¶
To bootstrap SOPS on a leaf cluster, create a new cluster using the SOPS template from the Create Cluster page and fill in the following SOPS-related values in the form:
What to expect¶
Security Recommendations¶
Access to sops decryption secrets should be restricted and allowed only to be read by flux's kustomize controller. This can be done using Kubernetes RBAC.
Here's an example of how you can use RBAC to restrict access to sops decryption secrets:
apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+ name: sops-secrets-role
+rules:
+- apiGroups: [""]
+ resources: ["secrets"]
+ resourceNames: ["sops-gpg-private-key", "sops-age-private-key"]
+ verbs: ["get", "watch", "list"]
+Expand to view the RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+ name: sops-secrets-rolebinding
+roleRef:
+ apiGroup: rbac.authorization.k8s.io
+ kind: Role
+ name: sops-secrets-role
+subjects:
+- kind: ServiceAccount
+ name: kustomize-controller
+Warning
You would need to ensure that no other rolebindings or clusterrolebndings would allow reading the the decryption secret at any time. This could be achieved by leveraging policy capabilities to detect existing and prevent future creation of roles that would grant read secrets permissions.
SecretSync ENTERPRISE¶
It provides semantics to sync Kuberentes Secrets from management cluster to leaf clusters.
apiVersion: capi.weave.works/v1alpha1
+kind: SecretSync
+metadata:
+ name: my-dev-secret-syncer
+ namespace: default
+spec:
+ clusterSelector:
+ matchLabels:
+ environment: dev
+ secretRef:
+ name: my-dev-secret
+ targetNamespace: my-namespace
+Specification¶
The documentation for the api version capi.weave.works/v1alpha1
type SecretSync struct {
+ metav1.TypeMeta `json:",inline"`
+ metav1.ObjectMeta `json:"metadata,omitempty"`
+ Spec SecretSyncSpec `json:"spec,omitempty"`
+ Status SecretSyncStatus `json:"status,omitempty"`
+}
+
+// SecretSyncSpec
+type SecretSyncSpec struct {
+ // Label selector for Clusters. The Clusters that are
+ // selected by this will be the ones affected by this SecretSync.
+ // It must match the Cluster labels. This field is immutable.
+ // Label selector cannot be empty.
+ ClusterSelector metav1.LabelSelector `json:"clusterSelector"`
+ // SecretRef specifies the Secret to be bootstrapped to the matched clusters
+ // Secret must be in the same namespace of the SecretSync object
+ SecretRef v1.LocalObjectReference `json:"secretRef"`
+ // TargetNamespace specifies the namespace which the secret should be bootstrapped in
+ // The default value is the namespace of the referenced secret
+ //+optional
+ TargetNamespace string `json:"targetNamespace,omitempty"`
+}
+
+// SecretSyncStatus secretsync object status
+type SecretSyncStatus struct {
+ // SecretVersions a map contains the ResourceVersion of the secret of each cluster
+ // Cluster name is the key and secret's ResourceVersion is the value
+ SecretVersions map[string]string `json:"versions"`
+}
+Weave Gitops Security¶
This document defines security reporting, handling, disclosure, and audit information for Weave Gitops.
Security Process¶
Report a Vulnerability¶
Handling¶
Disclosures¶
Vulnerability disclosures announced publicly. Disclosures will contain an overview, details about the vulnerability, a fix that will typically be an update, and optionally a workaround if one is available.
We will coordinate publishing disclosures and security releases in a way that is realistic and necessary for end users. We prefer to fully disclose the vulnerability as soon as possible once a user mitigation is available. Disclosures will always be published in a timely manner after a release is published that fixes the vulnerability.
Advisories¶
Here is an overview of all our published security advisories.
Weave Gitops OSS¶
| Date | CVE | Security Advisory | Severity | Affected version(s) |
|---|---|---|---|---|
| 2022-06-23 | CVE-2022-31098 | Weave GitOps leaked cluster credentials into logs on connection errors | Critical | <= 0.8.1-rc.5 |
Weave Gitops Enterprise¶
| Date | CVE | Security Advisory | Severity | Affected version(s) |
|---|---|---|---|---|
| 2022-08-27 | CVE-2022-38790 | Malicious links can be crafted by users and shown in the UI | Critical | < v0.9.0-rc.5 |
Get Started with the Terraform Controller¶
Preflight Checks¶
To set up the Terraform Controller (TF-Controller), follow the steps in the preflight checks. Here is a summary of what you will need to do:
The exact steps for setting up the TF-controller will depend on the specific environment and infrastructure that you are using. The project's documentation provides additional information to help with setup.
Setup¶
Perform the following actions to set up TF-Controller:
Assuming your username is $GITHUB_USER, you can create a new repository called gitops-tf-controller using the following command:
export GITHUB_USER=<your github username>
+export GITHUB_TOKEN=<your github personal access token>
+
+gh repo create $GITHUB_USER/gitops-tf-controller
+mkdir -p ./cluster/my-cluster/infra/
+Download the TF-controller manifest from the release location and save it to ./cluster/my-cluster/infra/tf-controller.yaml—placing the file tf-controller.yaml in this directory:
curl -s https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/release.yaml > ./cluster/my-cluster/infra/tf-controller.yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+ - tf-controller.yaml
+Add the kustomization.yaml file to your Git repository, then push the changes to your repository.
If you want to use TF-Controller with the Notification Controller, you will also need to modify the manifest to enable the two controllers to work together. The exact steps for doing this will depend on the specific requirements of your environment and the configuration of the Notification Controller. You may need to refer to the documentation for the TF-Controller and Notification Controller for more information on how to set this up.
Other Installation Methods¶
Before using TF-Controller, you must install Flux by using either flux install or the flux bootstrap command. Make sure you have the latest version of Flux. After that, you can install TF-controller with Flux HelmRelease with this command:
kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/release.yaml
+For the most recent TF-Controller release candidate, please use rc.yaml:
kubectl apply -f https://raw.githubusercontent.com/weaveworks/tf-controller/main/docs/rc.yaml
+or manually with Helm by:
# Add tf-controller helm repository
+helm repo add tf-controller https://weaveworks.github.io/tf-controller/
+
+# Install tf-controller
+helm upgrade -i tf-controller tf-controller/tf-controller \
+ --namespace flux-system
+For details on configurable parameters of the TF-controller chart, please see this chart Readme.
Alternatively, you can install TF-controller via kubectl:
export TF_CON_VER=v0.14.0
+kubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.crds.yaml
+kubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.rbac.yaml
+kubectl apply -f https://github.com/weaveworks/tf-controller/releases/download/${TF_CON_VER}/tf-controller.deployment.yaml
+Quick Start¶
Here's a simple example of how to GitOps your Terraform resources with TF-controller and Flux.
Define Source¶
First, define a Source controller's source (GitRepository, Bucket, OCIRepository)—for example:
apiVersion: source.toolkit.fluxcd.io/v1beta1
+kind: GitRepository
+metadata:
+ name: helloworld
+ namespace: flux-system
+spec:
+ interval: 30s
+ url: https://github.com/tf-controller/helloworld
+ ref:
+ branch: main
+The GitOps Automation Mode¶
In this mode, Terraform resources will be planned and automatically applied for you. Enable it by setting .spec.approvePlan=auto:
apiVersion: infra.contrib.fluxcd.io/v1alpha2
+kind: Terraform
+metadata:
+ name: helloworld
+ namespace: flux-system
+spec:
+ interval: 1m
+ approvePlan: auto
+ path: ./
+ sourceRef:
+ kind: GitRepository
+ name: helloworld
+ namespace: flux-system
+For a full list of features and how to use them, please visit the Terraform overview.
Troubleshooting¶
Getting a drift detected event message when it's a change of source that triggered the update¶
Whenever you change a source, you will get a new plan. TF-controller picks up the new plan and applies it. Drift happens if, and only if, the live system changes intentionally. Then TF-controller will generate a lengthy message see an example stating that a drift has occurred. If there is drift, the icon will be red in the TF Objects > Status column of the WGE UI.
Other Examples¶
Overview¶
Terraform Controller (TF-Controller) is a reliable tool for managing your infrastructure and application resources using the GitOps approach, all at your own pace. An open source project created by Weaveworks, the makers of Flux, TF-Controller follows patterns established by Flux and integrates with Weave GitOps.
TF-Controller makes the following GitOps models available to suit your specific needs:
To get started with TF-controller, simply follow the provided getting started guide. You can also find extensive documentation here—it covers API references, CLI references, and how-to's for common situations.
With Weave GitOps Enterprise, you can manage Terraform objects the same way you can with Kustomization and HelmReleases:
Features¶
Dependencies¶
TF-controller has its own versioning system that is separate from the versioning system used by Weave GitOps. This means that you can install and use TF-controller independently of Weave GitOps—it will not be affected by the version of Weave GitOps that you are using.
Here is the dependency matrix:
| Version | Terraform | Source Controller | Flux v2 |
|---|---|---|---|
| v0.14.0 | v1.3.9 | v0.35.1 | v0.40.x |
| v0.13.1 | v1.3.1 | v0.31.0 | v0.38.x |
Using Terraform Templates ENTERPRISE¶
This guide will show you how to use a template to create a Terraform resource in Weave GitOps Enterprise.
CLI Guide¶
Prerequisites¶
1. Add a template to your cluster¶
Add the following template to a path in your Git repository that is synced by Flux. For example, in the Installation guide, we set the path that is synced by Flux to ./clusters/management.
Commit and push these changes. Once a template is available in the cluster, it can be used to create a resource, which will be shown in the next step.
Expand to see ./clusters/management/tf-template.yaml
./clusters/management/tf-template.yaml
---
+apiVersion: clustertemplates.weave.works/v1alpha2
+kind: GitOpsTemplate
+metadata:
+name: tf-template
+namespace: default
+spec:
+description:
+ This is a sample WGE template that will be translated into a tf-controller specific template.
+params:
+ - name: RESOURCE_NAME
+ description: Resource Name
+resourcetemplates:
+ - content:
+ - apiVersion: infra.contrib.fluxcd.io/v1alpha1
+ kind: Terraform
+ metadata:
+ name: ${RESOURCE_NAME}
+ namespace: flux-system
+ spec:
+ interval: 1h
+ path: ./
+ approvePlan: auto
+ alwaysCleanupRunnerPod: true
+ sourceRef:
+ kind: GitRepository
+ name: flux-system
+ namespace: flux-system
+Verify that your template is in the cluster:
kubectl get gitopstemplates.clustertemplates.weave.works -A
+NAME AGE
+sample-wge-tf-controller-template 14m
+If the template does not appear immediately, reconcile the changes with Flux:
flux reconcile kustomization flux-system
+► annotating Kustomization flux-system in flux-system namespace
+✔ Kustomization annotated
+◎ waiting for Kustomization reconciliation
+✔ applied revision main/e6f5f0c3925bcfecdb50bceb12af9a87677d2213
+2. Use the template to create a resource¶
A resource can be created from a template by specifying the template's name and supplying values to it, as well as your Weave GitOps Enterprise username, password, and HTTP API endpoint.
gitops add terraform --from-template sample-wge-tf-controller-template \
+--set="RESOURCE_NAME"="name" \
+--username=<username> --password=<password> \
+--endpoint https://localhost:8000 \
+--url https://github.com/myawesomeorg/myawesomerepo
+
+Created pull request: https://github.com/myawesomeorg/myawesomerepo/pull/5
+This will create a PR in your Git repository with a TF-Controller manifest. Once the PR is merged, TF-Controller will supply the values to the Terraform manifest, apply the Terraform manifest to create the resource, and reconcile any changes that you make to the Terraform manifest!
This template can be used to create multiple resources out of the same Terraform manifest by supplying different values to the template. Any changes to the Terraform manifest will be reconciled automatically to all resources.
3. List available templates¶
Get a specific template that can be used to create a Terraform resource:
gitops get template terraform sample-wge-tf-controller-template --endpoint https://localhost:8000 --username=<username> --password=<password>
+NAME PROVIDER DESCRIPTION ERROR
+sample-wge-tf-controller-template This is a sample WGE template that will be translated into a tf-controller specific template.
+List all the templates available on the cluster:
gitops get template terraform --endpoint https://localhost:8000 --username=<username> --password=<password>
+NAME PROVIDER DESCRIPTION ERROR
+sample-aurora-tf-template This is a sample Aurora RDS template.
+sample-wge-tf-controller-template This is a sample WGE template that will be translated into a tf-controller specific template.
+4. List the parameters of a template¶
List all the parameters that can be defined on a specific template:
gitops get template terraform tf-controller-aurora --list-parameters --endpoint https://localhost:8000 --username=<username> --password=<password>
+NAME REQUIRED DESCRIPTION OPTIONS
+RESOURCE_NAME false Resource Name
+Use Case: Create an Aurora RDS with WGE¶
BONUS
For a more advanced example, here is a template to create an Aurora RDS cluster using WGE with Flux and the TF-Controller.
Pre-requisites¶
1. Configure a way to manage secrets¶
Configure a way to safely store Secrets. One method is to use the Mozilla SOPS CLI, but there are other ways, such as Sealed Secrets or Vaults.
Follow the steps in the Flux docs except for the "Configure in-cluster secrets decryption" step! This step looks slightly different for WGE. Instead of re-creating the controllers, you can configure the kustomize-controller as instructed below.
In your Git repository source, add the following to your kustomize-controller configuration:
cat <<EOF >> ./clusters/<cluster-name>/flux-system/gotk-sync.yaml
+ decryption:
+ provider: sops
+ secretRef:
+ name: sops-gpg
+EOF
+2. Encrypt and store your credentials in your Git repository¶
Create a Secret to store sensitive values such as the following: - DB username - DB password - AWS Access Key ID - AWS Secret Access Key - AWS Role ARN
Note
If following the Flux guide, this steps corresponds to "Encrypting secrets using OpenPGP". You can stop following the Flux guide at this step.
For example, here is what you would do if using the SOPS method:
kubectl -n flux-system create secret generic tf-controller-auth \
+--from-literal=master_username=admin \
+--from-literal=master_password=change-me \
+--from-literal=aws_access_key=AKIAIOSFODNN7EXAMPLE \
+--from-literal=aws_secret_key="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
+--from-literal=aws_role_arn="arn:aws:iam::012345678910:role/wge-tf-controller-example" \
+--dry-run=client \
+-o yaml > tf-controller-auth.yaml
+Then, encrypt the secret:
sops --encrypt --in-place tf-controller-auth.yaml
+Commit and push your changes. You can now store encrypted secrets to your Git repository.
4. Add the manifests to your cluster¶
Add the following Terraform manifest to the root of your Git repository.
Expand to see Terraform manifest
./rds.tf
terraform {
+required_providers {
+ aws = {
+ source = "hashicorp/aws"
+ version = "~> 3.0"
+ }
+}
+}
+
+variable "cluster_identifier" {}
+variable "database_name" {}
+variable "master_username" {}
+variable "master_password" {}
+variable "backup_retention_period" {}
+variable "region" {}
+variable "aws_access_key" {}
+variable "aws_secret_key" {}
+variable "aws_role_arn" {}
+
+provider "aws" {
+region = var.region
+access_key = var.aws_access_key
+secret_key = var.aws_secret_key
+
+assume_role {
+ role_arn = var.aws_role_arn
+}
+}
+
+locals {
+engine = "aurora-mysql"
+engine_version = "5.7.mysql_aurora.2.07.5"
+port = 3306
+}
+
+data "aws_availability_zones" "available" {
+state = "available"
+
+filter {
+ name = "group-name"
+ values = [var.region]
+}
+}
+
+resource "aws_rds_cluster" "mycluster" {
+cluster_identifier = var.cluster_identifier
+engine = local.engine
+engine_version = local.engine_version
+port = local.port
+availability_zones = slice(data.aws_availability_zones.available.names, 0, 3)
+database_name = var.database_name
+master_username = var.master_username
+master_password = var.master_password
+backup_retention_period = var.backup_retention_period
+skip_final_snapshot = true
+apply_immediately = true
+}
+
+resource "aws_rds_cluster_instance" "cluster_instance" {
+count = 1
+identifier = "${aws_rds_cluster.mycluster.id}-${count.index}"
+cluster_identifier = aws_rds_cluster.mycluster.id
+instance_class = "db.t3.small"
+engine = aws_rds_cluster.mycluster.engine
+engine_version = aws_rds_cluster.mycluster.engine_version
+}
+Add the following template to a path in your Git repository that is synced by Flux. In the quickstart guide, we set this path to ./clusters/management.
Expand to see Terraform manifest at ./clusters/management/rds-template.yaml
./clusters/management/rds-template.yaml
---
+apiVersion: clustertemplates.weave.works/v1alpha2
+kind: GitOpsTemplate
+metadata:
+name: rds-template
+namespace: default
+spec:
+description: This is a sample Aurora RDS template.
+params:
+ - name: RESOURCE_NAME
+ description: Resource Name
+ - name: CLUSTER_IDENTIFIER
+ description: Cluster Identifier
+ - name: DATABASE_NAME
+ description: Database Name
+ - name: BACKUP_RETENTION_PERIOD
+ description: Backup Retention Period
+ - name: REGION
+ description: Region
+resourcetemplates:
+ - contents:
+ - apiVersion: infra.contrib.fluxcd.io/v1alpha1
+ kind: Terraform
+ metadata:
+ name: ${RESOURCE_NAME}
+ namespace: flux-system
+ spec:
+ interval: 1h
+ path: ./
+ approvePlan: auto
+ alwaysCleanupRunnerPod: true
+ vars:
+ - name: cluster_identifier
+ value: ${CLUSTER_IDENTIFIER}
+ - name: database_name
+ value: ${DATABASE_NAME}
+ - name: backup_retention_period
+ value: ${BACKUP_RETENTION_PERIOD}
+ - name: region
+ value: ${REGION}
+ varsFrom:
+ - kind: Secret
+ name: tf-controller-auth
+ sourceRef:
+ kind: GitRepository
+ name: flux-system
+ namespace: flux-system
+Commit and push your changes.
Tip
You can change the location where you keep your Terraform manifests in your Git source (which the TF-Controller will reconcile) by configuring spec.resourcetemplates.spec.path.
5. Use the template to create the RDS¶
gitops add terraform --from-template rds-template \
+--username=<username> --password=<password> \
+--endpoint https://localhost:8000 \
+--url https://github.com/myawesomeorg/myawesomerepo \
+--set "RESOURCE_NAME"="tf-controller-aurora","CLUSTER_IDENTIFIER"="super-awesome-aurora","DATABASE_NAME"="db1","BACKUP_RETENTION_PERIOD"=5,"REGION"="us-west-2"
+
+Created pull request: https://github.com/myawesomeorg/myawesomerepo/pull/6
+Merge the PR in your Git repository to add the TF-Controller manifest. TF-Controller will supply the values to the Terraform manifest, apply the Terraform manifest to create the resource, and reconcile any changes that you make to the Terraform manifest.
Any changes to your Terraform manifest will be automatically reconciled by the TF-controller with Flux.
You can re-use this template to create multiple Terraform resources, each with a different set of values!
Make sure to delete the newly created RDS resources to not incur additional costs.
Introduction ENTERPRISE¶
Workspaces¶
Organizations working with Kubernetes have a tremendous need to manage tenancy for numerous software delivery teams. Weave GitOps Workspaces offers tenancy management for Kubernetes clusters at scale. It’s built on top of Flux's powerful approach to managing tenancy, and adds policies that will help you to define finer-grain rules on your tenants.
With WGE Workspaces, all it takes for platform operators to create workspaces is a single CLI command that generates:
Multi Tenancy ENTERPRISE¶
Multi tenancy provides users with the ability to define boundaries to multiple engineering teams working on a single cluster. Through a simple interface it adds permissions to the necessary Kubernetes resources to make it easy for customers to manage their multiple tenants.
WGE multi tenancy expands on the multi tenancy feature provided by flux. In addition to creating the necessary Kubernetes tenancy resources that flux adds, multi tenancy in WGE also adds the following: - Defining tenancy using a single yaml file that serves as a source of truth for the organization - Makes use of WGE policy features to enforce non Kubernetes native permissions
Prerequisites¶
How it works¶
gitops command line tool is responsible for creating the multi tenancy resources. The tool is distributed as part of WGE offering. It reads the definitions of a yaml file and can either apply the necessary changes directly to the cluster or output it to stdout so it can be saved into a file and pushed to a repo to be reconciled by flux.
To make use of the policy features, policy agent needs to be installed in the necessary cluster(s).
Tenancy file¶
Below is an example of a tenancy file:
Expand to view
tenancy.yaml
---
+tenants:
+- name: first-tenant
+ namespaces:
+ - first-ns
+- name: second-tenant
+ namespaces:
+ - second-test-ns
+ - second-dev-ns
+ allowedRepositories:
+ - kind: GitRepository
+ url: https://github.com/testorg/testrepo
+ - kind: GitRepository
+ url: https://github.com/testorg/testinfo
+ - kind: Bucket
+ url: minio.example.com
+ - kind: HelmRepository
+ url: https://testorg.github.io/testrepo
+ allowedClusters:
+ - kubeConfig: cluster-1-kubeconfig
+ - kubeConfig: cluster-2-kubeconfig
+ teamRBAC:
+ groupNames:
+ - foo-group
+ - bar-group
+ rules:
+ - apiGroups:
+ - ''
+ resources:
+ - 'namespaces'
+ - 'pods'
+ verbs:
+ - 'list'
+ - 'get'
+ deploymentRBAC:
+ bindRoles:
+ - name: foo-role
+ kind: Role
+ rules:
+ - apiGroups:
+ - ''
+ resources:
+ - 'namespaces'
+ - 'pods'
+ verbs:
+ - 'list'
+ - 'get'
+serviceAccount:
+name: "reconcilerServiceAccount"
+The file above defines two tenants: first-tenant and second-tenant as follows:
Global options:
Gitops create tenants command¶
The command creates the necessary resources to apply multi tenancy on the user's cluster. To use the command to apply the resources directly the user needs to have the necessary configuration to connect to the desired cluster. The command considers the tenancy file as a source of truth and will change the cluster state to match what is currently described in the file.
For more control on a specific tenant a tenancy file should be used, the command allows the creation of the base resources that defines a tenancy through the arguments:
gitops create tenants --name test-tenant --namespace test-ns1 --namespace test-ns2
+Expand to view command output
namespace/test-ns1 created
+test-ns1/serviceaccount/test-tenant created
+test-ns1/rolebinding.rbac.authorization.k8s.io/test-tenant-service-account-cluster-admin created
+namespace/test-ns2 created
+test-ns2/serviceaccount/test-tenant created
+test-ns2/rolebinding.rbac.authorization.k8s.io/test-tenant-service-account-cluster-admin created
+policy.pac.weave.works/weave.policies.tenancy.test-tenant-allowed-application-deploy created
+The above will create the namespaces and permissions through a ServiceAccount with the same name as the tenant, test-tenant in the case of the above example, in each required namespace. The same can be done through a file as follows:
tenants:
+ - name: test-tenant
+ namespaces:
+ - test-ns1
+ - test-ns2
+gitops create tenants --from-file tenants.yaml
+Expand to view command output
namespace/test-ns1 created
+test-ns1/serviceaccount/test-tenant created
+test-ns1/rolebinding.rbac.authorization.k8s.io/test-tenant-service-account-cluster-admin created
+namespace/test-ns2 created
+test-ns2/serviceaccount/test-tenant created
+test-ns2/rolebinding.rbac.authorization.k8s.io/test-tenant-service-account-cluster-admin created
+policy.pac.weave.works/weave.policies.tenancy.test-tenant-allowed-application-deploy created
+To check the resources that would be deployed first use the export flag:
gitops create tenants --from-file tenants.yaml --export
+Expand to view command output
apiVersion: v1
+kind: Namespace
+metadata:
+creationTimestamp: null
+labels:
+ toolkit.fluxcd.io/tenant: test-tenant
+name: test-ns1
+spec: {}
+status: {}
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+creationTimestamp: null
+labels:
+ toolkit.fluxcd.io/tenant: test-tenant
+name: test-tenant
+namespace: test-ns1
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+creationTimestamp: null
+labels:
+ toolkit.fluxcd.io/tenant: test-tenant
+name: test-tenant-service-account-cluster-admin
+namespace: test-ns1
+roleRef:
+apiGroup: rbac.authorization.k8s.io
+kind: ClusterRole
+name: cluster-admin
+subjects:
+- kind: ServiceAccount
+name: test-tenant
+namespace: test-ns1
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+creationTimestamp: null
+labels:
+ toolkit.fluxcd.io/tenant: test-tenant
+name: test-ns2
+spec: {}
+status: {}
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+creationTimestamp: null
+labels:
+ toolkit.fluxcd.io/tenant: test-tenant
+name: test-tenant
+namespace: test-ns2
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+creationTimestamp: null
+labels:
+ toolkit.fluxcd.io/tenant: test-tenant
+name: test-tenant-service-account-cluster-admin
+namespace: test-ns2
+roleRef:
+apiGroup: rbac.authorization.k8s.io
+kind: ClusterRole
+name: cluster-admin
+subjects:
+- kind: ServiceAccount
+name: test-tenant
+namespace: test-ns2
+---
+apiVersion: pac.weave.works/v2beta2
+kind: Policy
+metadata:
+creationTimestamp: null
+labels:
+ toolkit.fluxcd.io/tenant: test-tenant
+name: weave.policies.tenancy.test-tenant-allowed-application-deploy
+spec:
+category: weave.categories.tenancy
+code: |
+ package weave.tenancy.allowed_application_deploy
+
+ controller_input := input.review.object
+ violation[result] {
+ namespaces := input.parameters.namespaces
+ targetNamespace := controller_input.spec.targetNamespace
+ not contains_array(targetNamespace, namespaces)
+ result = {
+ "issue detected": true,
+ "msg": sprintf("using target namespace %v is not allowed", [targetNamespace]),
+ }
+ }
+ violation[result] {
+ serviceAccountName := controller_input.spec.serviceAccountName
+ serviceAccountName != input.parameters.service_account_name
+ result = {
+ "issue detected": true,
+ "msg": sprintf("using service account name %v is not allowed", [serviceAccountName]),
+ }
+ }
+ contains_array(item, items) {
+ items[_] = item
+ }
+description: Determines which helm release and kustomization can be used in a tenant
+how_to_solve: ""
+id: weave.policies.tenancy.test-tenant-allowed-application-deploy
+name: test-tenant allowed application deploy
+parameters:
+- name: namespaces
+ required: false
+ type: array
+ value:
+ - test-ns1
+ - test-ns2
+- name: service_account_name
+ required: false
+ type: string
+ value: test-tenant
+provider: kubernetes
+severity: high
+standards: []
+tags:
+- tenancy
+targets:
+ kinds:
+ - HelmRelease
+ - Kustomization
+ labels: []
+ namespaces:
+ - test-ns1
+ - test-ns2
+status: {}
+---
+Applying the resources through the command line is not usually recommended. For WGE the recommended way is to commit the result of the create tenants command to source control and let flux handle deployment. To achieve that you can save the result of the export to a file:
gitops create tenants --from-file tenants.yaml --export > clusters/management/tenants.yaml
+Workspaces List View ENTERPRISE¶
From the side menu, you can click on the Workspaces tab to go to the workspaces list view.
This view lists workspaces across all clusters. You can filter workspaces by their clusters or their names.
Workspace Details View¶
You can go to this view by clicking on the name of the workspace in the Workspaces List View.
In this view you can see all details of the workspace such as its name, namespace, and all resources related to this workspace.
Packages:
+ +templates.weave.works/v1alpha1
+Package v1alpha1 contains API Schema definitions for the gitopssets v1alpha1 API group
+Resource Types: +GitOpsSet +
+GitOpsSet is the Schema for the gitopssets API
+| Field | +Description | +||||||||
|---|---|---|---|---|---|---|---|---|---|
+apiVersion+string |
+
+templates.weave.works/v1alpha1
+ |
+||||||||
+kind+string + |
+
+GitOpsSet
+ |
+||||||||
+metadata+ + +Kubernetes meta/v1.ObjectMeta + + + |
+
+Refer to the Kubernetes API documentation for the fields of the
+metadata field.
+ |
+||||||||
+spec+ + +GitOpsSetSpec + + + |
+
+ + +
|
+||||||||
+status+ + +GitOpsSetStatus + + + |
++ | +
APIClientGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+APIClientGenerator defines a generator that queries an API endpoint and uses +that to generate data.
+| Field | +Description | +
|---|---|
+interval+ + +Kubernetes meta/v1.Duration + + + |
+
+ The interval at which to poll the API endpoint. + |
+
+endpoint+ +string + + |
+
+(Optional)
+ This is the API endpoint to use. + |
+
+method+ +string + + |
+
+ Method defines the HTTP method to use to talk to the endpoint. + |
+
+jsonPath+ +string + + |
+
+ JSONPath is string that is used to modify the result of the API +call. +This can be used to extract a repeating element from a response. +https://kubernetes.io/docs/reference/kubectl/jsonpath/ + |
+
+headersRef+ + +HeadersReference + + + |
+
+(Optional)
+ HeadersRef allows optional configuration of a Secret or ConfigMap to add +additional headers to an outgoing request. +For example, a Secret with a key Authorization: Bearer abc123 could be +used to configure an authorization header. + |
+
+body+ + +Kubernetes pkg/apis/apiextensions/v1.JSON + + + |
+
+(Optional)
+ Body is set as the body in a POST request. +If set, this will configure the Method to be POST automatically. + |
+
+singleElement+ +bool + + |
+
+(Optional)
+ SingleElement means generate a single element with the result of the API +call. +When true, the response must be a JSON object and will be returned as a +single element, i.e. only one element will be generated containing the +entire object. + |
+
+secretRef+ + +Kubernetes core/v1.LocalObjectReference + + + |
+
+ Reference to Secret in same namespace with a field “caFile” which +provides the Certificate Authority to trust when making API calls. + |
+
ClusterGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+ClusterGenerator defines a generator that queries the cluster API for +relevant clusters.
+| Field | +Description | +
|---|---|
+selector+ + +Kubernetes meta/v1.LabelSelector + + + |
+
+(Optional)
+ Selector is used to filter the clusters that you want to target. +If no selector is provided, no clusters will be matched. + |
+
ConfigGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+ConfigGenerator loads a referenced ConfigMap or +Secret from the Cluster and makes it available as a resource.
+| Field | +Description | +
|---|---|
+kind+ +string + + |
+
+ Kind of the referent. + |
+
+name+ +string + + |
+
+ Name of the referent. + |
+
GitOpsSetGenerator +
++(Appears on: +GitOpsSetSpec) +
+GitOpsSetGenerator is the top-level set of generators for this GitOpsSet.
+| Field | +Description | +
|---|---|
+list+ + +ListGenerator + + + |
++ | +
+pullRequests+ + +PullRequestGenerator + + + |
++ | +
+gitRepository+ + +GitRepositoryGenerator + + + |
++ | +
+ociRepository+ + +OCIRepositoryGenerator + + + |
++ | +
+matrix+ + +MatrixGenerator + + + |
++ | +
+cluster+ + +ClusterGenerator + + + |
++ | +
+apiClient+ + +APIClientGenerator + + + |
++ | +
+imagePolicy+ + +ImagePolicyGenerator + + + |
++ | +
+config+ + +ConfigGenerator + + + |
++ | +
GitOpsSetNestedGenerator +
++(Appears on: +MatrixGenerator) +
+GitOpsSetNestedGenerator describes the generators usable by the MatrixGenerator. +This is a subset of the generators allowed by the GitOpsSetGenerator because the CRD format doesn’t support recursive declarations.
+| Field | +Description | +
|---|---|
+name+ +string + + |
+
+(Optional)
+ Name is an optional field that will be used to prefix the values generated +by the nested generators, this allows multiple generators of the same +type in a single Matrix generator. + |
+
+list+ + +ListGenerator + + + |
++ | +
+gitRepository+ + +GitRepositoryGenerator + + + |
++ | +
+ociRepository+ + +OCIRepositoryGenerator + + + |
++ | +
+pullRequests+ + +PullRequestGenerator + + + |
++ | +
+cluster+ + +ClusterGenerator + + + |
++ | +
+apiClient+ + +APIClientGenerator + + + |
++ | +
+imagePolicy+ + +ImagePolicyGenerator + + + |
++ | +
+config+ + +ConfigGenerator + + + |
++ | +
GitOpsSetSpec +
++(Appears on: +GitOpsSet) +
+GitOpsSetSpec defines the desired state of GitOpsSet
+| Field | +Description | +
|---|---|
+suspend+ +bool + + |
+
+(Optional)
+ Suspend tells the controller to suspend the reconciliation of this +GitOpsSet. + |
+
+generators+ + +[]GitOpsSetGenerator + + + |
+
+ Generators generate the data to be inserted into the provided templates. + |
+
+templates+ + +[]GitOpsSetTemplate + + + |
+
+ Templates are a set of YAML templates that are rendered into resources +from the data supplied by the generators. + |
+
+serviceAccountName+ +string + + |
+
+(Optional)
+ The name of the Kubernetes service account to impersonate +when reconciling this Kustomization. + |
+
GitOpsSetStatus +
++(Appears on: +GitOpsSet) +
+GitOpsSetStatus defines the observed state of GitOpsSet
+| Field | +Description | +
|---|---|
+ReconcileRequestStatus+ + +github.com/fluxcd/pkg/apis/meta.ReconcileRequestStatus + + + |
+
+
+(Members of |
+
+observedGeneration+ +int64 + + |
+
+(Optional)
+ ObservedGeneration is the last observed generation of the HelmRepository +object. + |
+
+conditions+ + +[]Kubernetes meta/v1.Condition + + + |
+
+(Optional)
+ Conditions holds the conditions for the GitOpsSet + |
+
+inventory+ + +ResourceInventory + + + |
+
+(Optional)
+ Inventory contains the list of Kubernetes resource object references that +have been successfully applied + |
+
GitOpsSetTemplate +
++(Appears on: +GitOpsSetSpec) +
+GitOpsSetTemplate describes a resource to create
+| Field | +Description | +
|---|---|
+repeat+ +string + + |
+
+ Repeat is a JSONPath string defining that the template content should be +repeated for each of the matching elements in the JSONPath expression. +https://kubernetes.io/docs/reference/kubectl/jsonpath/ + |
+
+content+ + +k8s.io/apimachinery/pkg/runtime.RawExtension + + + |
+
+ Content is the YAML to be templated and generated. + |
+
GitRepositoryGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+GitRepositoryGenerator generates from files in a Flux GitRepository resource.
+| Field | +Description | +
|---|---|
+repositoryRef+ +string + + |
+
+ RepositoryRef is the name of a GitRepository resource to be generated from. + |
+
+files+ + +[]RepositoryGeneratorFileItem + + + |
+
+ Files is a set of rules for identifying files to be parsed. + |
+
+directories+ + +[]RepositoryGeneratorDirectoryItem + + + |
+
+ Directories is a set of rules for identifying directories to be +generated. + |
+
HeadersReference +
++(Appears on: +APIClientGenerator) +
+HeadersReference references either a Secret or ConfigMap to be used for +additional request headers.
+| Field | +Description | +
|---|---|
+kind+ +string + + |
+
+ The resource kind to get headers from. + |
+
+name+ +string + + |
+
+ Name of the resource in the same namespace to apply headers from. + |
+
ImagePolicyGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+ImagePolicyGenerator generates from the ImagePolicy.
+| Field | +Description | +
|---|---|
+policyRef+ +string + + |
+
+ PolicyRef is the name of a ImagePolicy resource to be generated from. + |
+
ListGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+ListGenerator generates from a hard-coded list.
+| Field | +Description | +
|---|---|
+elements+ + +[]Kubernetes pkg/apis/apiextensions/v1.JSON + + + |
++ | +
MatrixGenerator +
++(Appears on: +GitOpsSetGenerator) +
+MatrixGenerator defines a matrix that combines generators. +The matrix is a cartesian product of the generators.
+| Field | +Description | +
|---|---|
+generators+ + +[]GitOpsSetNestedGenerator + + + |
+
+ Generators is a list of generators to be combined. + |
+
+singleElement+ +bool + + |
+
+(Optional)
+ SingleElement means generate a single element with the result of the +merged generator elements. +When true, the matrix elements will be merged to a single element, with +whatever prefixes they have. +It’s recommended that you use the Name field to separate out elements. + |
+
OCIRepositoryGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+OCIRepositoryGenerator generates from files in a Flux OCIRepository resource.
+| Field | +Description | +
|---|---|
+repositoryRef+ +string + + |
+
+ RepositoryRef is the name of a OCIRepository resource to be generated from. + |
+
+files+ + +[]RepositoryGeneratorFileItem + + + |
+
+ Files is a set of rules for identifying files to be parsed. + |
+
+directories+ + +[]RepositoryGeneratorDirectoryItem + + + |
+
+ Directories is a set of rules for identifying directories to be +generated. + |
+
PullRequestGenerator +
++(Appears on: +GitOpsSetGenerator, +GitOpsSetNestedGenerator) +
+PullRequestGenerator defines a generator that queries a Git hosting service +for relevant PRs.
+| Field | +Description | +
|---|---|
+interval+ + +Kubernetes meta/v1.Duration + + + |
+
+ The interval at which to check for repository updates. + |
+
+driver+ +string + + |
+
+ Determines which git-api protocol to use. + |
+
+serverURL+ +string + + |
+
+(Optional)
+ This is the API endpoint to use. + |
+
+repo+ +string + + |
+
+ This should be the Repo you want to query. +e.g. my-org/my-repo + |
+
+secretRef+ + +Kubernetes core/v1.LocalObjectReference + + + |
+
+ Reference to Secret in same namespace with a field “password” which is an +auth token that can query the Git Provider API. + |
+
+labels+ +[]string + + |
+
+(Optional)
+ Labels is used to filter the PRs that you want to target. +This may be applied on the server. + |
+
+forks+ +bool + + |
+
+(Optional)
+ Fork is used to filter out forks from the target PRs if false, +or to include forks if true + |
+
RepositoryGeneratorDirectoryItem +
++(Appears on: +GitRepositoryGenerator, +OCIRepositoryGenerator) +
+RepositoryGeneratorDirectoryItem stores the information about a specific +directory to be generated from.
+| Field | +Description | +
|---|---|
+path+ +string + + |
++ | +
+exclude+ +bool + + |
++ | +
RepositoryGeneratorFileItem +
++(Appears on: +GitRepositoryGenerator, +OCIRepositoryGenerator) +
+RepositoryGeneratorFileItem defines a path to a file to be parsed when generating.
+| Field | +Description | +
|---|---|
+path+ +string + + |
+
+ Path is the name of a file to read and generate from can be JSON or YAML. + |
+
ResourceInventory +
++(Appears on: +GitOpsSetStatus) +
+ResourceInventory contains a list of Kubernetes resource object references that have been applied by a Kustomization.
+| Field | +Description | +
|---|---|
+entries+ + +[]ResourceRef + + + |
+
+ Entries of Kubernetes resource object references. + |
+
ResourceRef +
++(Appears on: +ResourceInventory) +
+ResourceRef contains the information necessary to locate a resource within a cluster.
+| Field | +Description | +
|---|---|
+id+ +string + + |
+
+ ID is the string representation of the Kubernetes resource object’s metadata, +in the format ‘namespace_name_group_kind’. + |
+
+v+ +string + + |
+
+ Version is the API version of the Kubernetes resource object’s kind. + |
+
+
diff --git a/userdocs/theme/partials/copyright.html b/userdocs/theme/partials/copyright.html
new file mode 100644
index 0000000000..feca0cd425
--- /dev/null
+++ b/userdocs/theme/partials/copyright.html
@@ -0,0 +1,10 @@
+This page was automatically generated with gen-crd-api-reference-docs
+
\ No newline at end of file
Site powered by Netlify ©
+Copyright © {{ build_date_utc.strftime('%Y') }} Weaveworks
+
+ Made with
+
+ Material for MkDocs
+
+