diff --git a/docs/feature/storage-backends/helm.mdx b/docs/feature/storage-backends/helm.mdx new file mode 100644 index 0000000..afade0a --- /dev/null +++ b/docs/feature/storage-backends/helm.mdx @@ -0,0 +1,242 @@ +# Helm + +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. + +## 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 + +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'; +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.