From 195efb4282b8ee1c5b79966f900c79bfa749ce20 Mon Sep 17 00:00:00 2001 From: Mateusz Szostok Date: Thu, 24 Mar 2022 17:14:03 +0100 Subject: [PATCH 1/2] Add Helm storage document --- docs/feature/storage-backends/helm.mdx | 240 ++++++++++++++++++ docs/feature/storage-backends/introduction.md | 3 +- 2 files changed, 242 insertions(+), 1 deletion(-) create mode 100644 docs/feature/storage-backends/helm.mdx diff --git a/docs/feature/storage-backends/helm.mdx b/docs/feature/storage-backends/helm.mdx new file mode 100644 index 0000000..046f527 --- /dev/null +++ b/docs/feature/storage-backends/helm.mdx @@ -0,0 +1,240 @@ +# Helm + +The Helm backend storage gives you an option to map the TypeInstance's value to a given Helm release. This solves problems with outdated static data about Helm release that are stored in built-in database. The functionality in a form of a dedicated storage backend is installed using Capact Action. This guide describes how to install and configure the Helm storage backends for Capact Local Hub. + +To learn more about Capact Local Hub storage backends, see the [Introduction](./introduction.md) document. + +## Features + +There are different options of using the Helm storage backend. In each option Helm backend works locally, which means that it can resolve only a given Helm release if it's installed on the same Kubernetes cluster. + +### Helm Release + +Provides the metadata for a given Helm release installed on the Kubernetes cluster. Returned **value** contains: + +```yaml +# Name specifies installed Helm release name. +name: rel-name +# Namespace specifies in which Kubernetes Namespace Helm release was installed. +namespace: rel-namespace +# Chart holds Helm Chart details. +chart: + # Name specifies Helm Chart name. + name: chart-name + # Version specifies the exact chart version. + version: installed-chart-version + # Repo specifies URL where to locate the requested chart. + repo: repo-url +``` + +Helm Release backend doesn't store any data. Thus, it works only on the Helm release fetched from the cluster. The **create** and **update** methods check only if a given Helm release is accessible. The **delete**, **lock**, and **unlock** methods don't execute any operation. + +### Helm Template + +Renders a given Go template against an installed Helm release. The output depends on the given **goTemplate** context property. + +Helm Template backend doesn't store any data. Thus, it works only on the Helm release fetched from the cluster. The **create** and **update** methods check only if a given Helm release is accessible and if provided Go template can be rendered. The **delete**, **lock**, and **unlock** methods don't execute any operation. + +## Prerequisites + +* [Capact CLI](../../cli/getting-started.mdx) installed. +* Cluster with Capact installation. See the [installation tutorial](../../installation/local.mdx). + +## Installation + +1. Create parameters: + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +
+ + + +```bash +cat > /tmp/helm-storage-input-params.yaml << ENDOFFILE +input-parameters: + version: 0.6.0-5f348f9 # optional +ENDOFFILE +``` + + + + +```bash +cat > /tmp/helm-storage-input-params.yaml << ENDOFFILE +input-parameters: + version: 0.6.0-5f348f9 # optional +ENDOFFILE + +cat > /tmp/helm-storage-install-policy.yaml << ENDOFFILE +interface: + rules: + - interface: + path: cap.interface.helm.storage.install + oneOf: + - implementationConstraints: + path: cap.implementation.helm.storage.install + inject: + additionalParameters: + - name: additional-parameters + value: # Change values which you need. + # The source of true for below values, can be found here: + # https://github.com/capactio/capact/blob/main/deploy/kubernetes/charts/helm-storage-backend/values.yaml + global: + containerRegistry: + path: ghcr.io/capactio + overrideTag: bb9b779 + image: + name: helm-storage-backend + pullPolicy: IfNotPresent + helmReleaseBackend: + enabled: true + service: + port: 50051 + type: ClusterIP + resources: + limits: + cpu: 100m + memory: 32Mi + requests: + cpu: 30m + memory: 16Mi + helmTemplateBackend: + enabled: true + service: + port: 50052 + type: ClusterIP + resources: + limits: + cpu: 1 + memory: 512Mi + requests: + cpu: 30m + memory: 16Mi + replicaCount: 1 + imagePullSecrets: [] + podAnnotations: {} + podSecurityContext: {} + # fsGroup: 2000 + securityContext: {} + autoscaling: + enabled: false + minReplicas: 1 + maxReplicas: 100 + targetCPUUtilizationPercentage: 80 + nodeSelector: {} + tolerations: [] + affinity: {} + - interface: + path: cap.* + oneOf: + - implementationConstraints: + requires: + - path: cap.core.type.platform.kubernetes +ENDOFFILE +``` + + + +
+ + +1. Create Action: + +
+ + + +```bash +capact act create cap.interface.helm.storage.install --name helm-storage -n capact-system --parameters-from-file /tmp/helm-storage-input-params.yaml +``` + + + + +```bash +capact act create cap.interface.helm.storage.install --name helm-storage -n capact-system --parameters-from-file /tmp/helm-storage-input-params.yaml --action-policy-from-file /tmp/helm-storage-install-policy.yaml +``` + + + +
+ +1. Wait for the Action to have the `READY_TO_RUN` status: + + ```bash + capact act get helm-storage -n capact-system + ``` + +1. Run Action: + + ```bash + capact act run helm-storage -n capact-system + ``` + +1. Watch the Action for completion: + + ```bash + capact act watch helm-storage -n capact-system + ``` + +1. Get output TypeInstances: + + ```bash + capact act get helm-storage -n capact-system -ojson | jq '.Actions[0].output.typeInstances' + ``` + + See the details of the installed: + - Helm Release backend: + ```bash + HELM_RELEASE_STORAGE_ID=$(capact act get helm-storage -n capact-system -ojson | jq '.Actions[0].output.typeInstances | map(select(.typeRef.path == "cap.type.helm.release.storage"))[0].id' -r) + capact ti get $HELM_RELEASE_STORAGE_ID -oyaml + ``` + - Helm Template backend: + ```bash + HELM_TEMPLATE_STORAGE_ID=$(capact act get helm-storage -n capact-system -ojson | jq '.Actions[0].output.typeInstances | map(select(.typeRef.path == "cap.type.helm.template.storage"))[0].id' -r) + capact ti get $HELM_TEMPLATE_STORAGE_ID -oyaml + ``` + +## Use Helm backends + +Once the Helm backends are installed, you can configure it for Helm related TypeInstances. + +For example, you can set a Global Policy to inject Helm backends to all Implementations that require them: + +```bash +cat > /tmp/helm-storage-policy.yaml << ENDOFFILE +interface: + default: # properties applied to all rules above + inject: + requiredTypeInstances: + - id: ${HELM_TEMPLATE_STORAGE_ID} + description: "Helm template" + - id: ${HELM_RELEASE_STORAGE_ID} + description: "Helm release" + rules: + - interface: + path: cap.* + oneOf: + - implementationConstraints: + requires: + - path: cap.core.type.platform.kubernetes + - implementationConstraints: {} +ENDOFFILE +capact policy apply -f /tmp/helm-storage-policy.yaml +``` + +To read more about TypeInstance backend configuration, see the [Definition of rules for TypeInstance](../policies/overview.md#definition-of-rules-for-typeinstance) section. diff --git a/docs/feature/storage-backends/introduction.md b/docs/feature/storage-backends/introduction.md index 58b7840..b3aee21 100644 --- a/docs/feature/storage-backends/introduction.md +++ b/docs/feature/storage-backends/introduction.md @@ -8,7 +8,7 @@ By default, Capact stores the state in a form of TypeInstances, that contain sta However, there are many cases, where static, unencrypted data is not enough. For example, some sensitive data should be stored in a secure way. Or, Helm chart details may quickly become outdated in case of any external change (e.g. upgrade with `helm` CLI). -That's why Capact introduced storage backends functionality. Storage backend is a service which manages external TypeInstance's `value` for every resource version, as well as the `lockedBy` piece of information. +That's why Capact introduced storage backends functionality. Storage backend is a service which manages external TypeInstance's `value` for every resource version, as well as the `lockedBy` piece of information. It supports full TypeInstance lifecycle, that is: create, get, update, delete, lock, unlock operations. @@ -18,6 +18,7 @@ It supports full TypeInstance lifecycle, that is: create, get, update, delete, l Currently, we have the following storage backends available: - [AWS Secrets Manager](./aws-secrets-manager.md) +- [Helm](./helm.mdx) Each storage backend is installed separately using Capact Actions. See corresponding documents for each storage to learn how to install and configure them. From a6a91cfffb7ddeb8dd543774cd8db37dcbfc1421 Mon Sep 17 00:00:00 2001 From: Mateusz Szostok Date: Mon, 28 Mar 2022 09:21:23 +0200 Subject: [PATCH 2/2] Apply suggestions after review --- docs/feature/storage-backends/helm.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/feature/storage-backends/helm.mdx b/docs/feature/storage-backends/helm.mdx index 046f527..afade0a 100644 --- a/docs/feature/storage-backends/helm.mdx +++ b/docs/feature/storage-backends/helm.mdx @@ -1,6 +1,6 @@ # Helm -The Helm backend storage gives you an option to map the TypeInstance's value to a given Helm release. This solves problems with outdated static data about Helm release that are stored in built-in database. The functionality in a form of a dedicated storage backend is installed using Capact Action. This guide describes how to install and configure the Helm storage backends for Capact Local Hub. +The Helm backend storage gives you an option to map the TypeInstance's value to a given Helm release installed in a cluster. This solves problems with outdated static data about Helm release that is stored in the built-in database. The functionality in a form of a dedicated storage backend is installed using Capact Action. This guide describes how to install and configure the Helm storage backends for Capact Local Hub. To learn more about Capact Local Hub storage backends, see the [Introduction](./introduction.md) document. @@ -42,6 +42,8 @@ Helm Template backend doesn't store any data. Thus, it works only on the Helm re ## Installation +In the default mode, both Helm storage backends are installed. To change it, copy the snippets from the “Customized” tab and change either **helmReleaseBackend.enabled** or **helmTemplateBackend.enabled** to `false` before creating input files. + 1. Create parameters: import Tabs from '@theme/Tabs';