#Working with Helm charts

#1. Understanding Helm

Helm is a package manager that simplifies the deployment of applications and services on Alauda Container Platform clusters. Helm uses a packaging format called charts. A Helm chart is a collection of files that describe Kubernetes resources. Creating a chart in a cluster generates a chart running instance called a release. Each time a chart is created, or a release is upgraded or rolled back, an incremental revision is created.

#1.1. Key features

Helm provides the ability to:

• Search for a large collection of charts in chart repositories
• Modify existing charts
• Create your own charts using Kubernetes resources
• Package applications and share them as charts

#1.2. Catalog

The Catalog is built on Helm and provides a comprehensive Chart distribution management platform, extending the limitations of the Helm CLI tool. The platform enables developers to more conveniently manage, deploy, and use charts through a user-friendly interface.

#Terminology Definitions

#1.3 Understanding HelmRequest

In Alauda Container Platform, Helm deployments are primarily managed through a custom resource called HelmRequest. This approach extends standard Helm functionality and integrates it seamlessly into the Kubernetes native resource model.

#Differences Between HelmRequest and Helm

Standard Helm uses CLI commands to manage releases, while Alauda Container Platform uses HelmRequest resources to define, deploy, and manage Helm charts. Key differences include:

1. Declarative vs Imperative: HelmRequest provides a declarative approach to Helm deployments, while traditional Helm CLI is imperative.
2. Kubernetes Native: HelmRequest is a custom resource directly integrated with the Kubernetes API.
3. Continuous Reconciliation: Captain continuously monitors and reconciles HelmRequest resources with their desired state.
4. Multi-cluster Support: HelmRequest supports deployments across multiple clusters through the platform.
5. Platform Feature Integration: HelmRequest can be integrated with other platform features, such as Application resources.

#HelmRequest and Application Integration

HelmRequest and Application resources have conceptual similarities, and users may want to view them uniformly. The platform provides a mechanism to synchronize HelmRequest as Application resources.

Users can mark a HelmRequest to be deployed as an Application by adding the following annotation:

alauda.io/create-app: "true"

When this feature is enabled, the platform UI displays additional fields and links to the corresponding Application page.

#Deployment Workflow

The workflow for deploying charts via HelmRequest includes:

1. User creates or updates a HelmRequest resource
2. HelmRequest contains chart references and values to apply
3. Captain processes the HelmRequest and creates a Helm Release
4. Release contains the deployed resources
5. Metis monitors HelmRequests with application annotations and synchronizes them to Applications
6. Application provides a unified view of deployed resources

#Component Definitions

• HelmRequest: Custom resource definition that describes the desired Helm chart deployment
• Captain: Controller that processes HelmRequest resources and manages Helm releases (source code available at https://github.com/alauda/captain)
• Release: Deployed instance of a Helm chart
• Charon: Component that monitors HelmRequests and creates corresponding Application resources
• Application: Unified representation of deployed resources, providing additional management capabilities
• Archon-api: Component responsible for specific advanced API functions within the platform

#2 Deploying Helm Charts as Applications via CLI

#2.1 Workflow Overview

Prepare chart → Package chart → Obtain API token → Create chart repository → Upload chart → Upload related images → Deploy application → Update application → Uninstall application → Delete chart repository

#2.2 Preparing the Chart

Helm uses a packaging format called charts. A chart is a collection of files that describe Kubernetes resources. A single chart can be used to deploy anything from a simple pod to a complex application stack.

Refer to the official documentation: Helm Charts Documentation

Example chart directory structure:

nginx/
├── Chart.lock
├── Chart.yaml
├── README.md
├── charts/
│   └── common/
│       ├── Chart.yaml
│       ├── README.md
│       ├── templates/
│       │   ├── _affinities.tpl
│       │   ├── _capabilities.tpl
│       │   ├── _errors.tpl
│       │   ├── _images.tpl
│       │   ├── _ingress.tpl
│       │   ├── _labels.tpl
│       │   ├── _names.tpl
│       │   ├── _secrets.tpl
│       │   ├── _storage.tpl
│       │   ├── _tplvalues.tpl
│       │   ├── _utils.tpl
│       │   ├── _warnings.tpl
│       │   └── validations/
│       │       ├── _cassandra.tpl
│       │       ├── _mariadb.tpl
│       │       ├── _mongodb.tpl
│       │       ├── _postgresql.tpl
│       │       ├── _redis.tpl
│       │       └── _validations.tpl
│       └── values.yaml
├── ci/
│   ├── ct-values.yaml
│   └── values-with-ingress-metrics-and-serverblock.yaml
├── templates/
│   ├── NOTES.txt
│   ├── _helpers.tpl
│   ├── deployment.yaml
│   ├── extra-list.yaml
│   ├── health-ingress.yaml
│   ├── hpa.yaml
│   ├── ingress.yaml
│   ├── ldap-daemon-secrets.yaml
│   ├── pdb.yaml
│   ├── server-block-configmap.yaml
│   ├── serviceaccount.yaml
│   ├── servicemonitor.yaml
│   ├── svc.yaml
│   └── tls-secrets.yaml
├── values.descriptor.yaml
├── values.schema.json
└── values.yaml

Key file descriptions:

• values.descriptor.yaml (optional): Works with ACP UI to display user-friendly forms
• values.schema.json (optional): Validates values.yaml content and renders a simple UI
• values.yaml (required): Defines chart deployment parameters

#2.3 Packaging the Chart

Use the helm package command to package the chart:

helm package nginx
# 输出: Successfully packaged chart and saved it to: /charts/nginx-8.8.0.tgz

#2.4 Obtaining an API Token

1. In Alauda Container Platform, click the avatar in the top-right corner => Profile
2. Click Add Api Token
3. Enter appropriate Description & Remaining Validity
4. Save the displayed token information (only shown once)

#2.5 Creating a Chart Repository

Create a local chart repository via API:

curl -k --request POST \
--url https://$ACP_DOMAIN/catalog/v1/chartrepos \
--header 'Authorization:Bearer $API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "apiVersion": "v1",
  "kind": "ChartRepoCreate",
  "metadata": {
    "name": "test",
    "namespace": "cpaas-system"
  },
  "spec": {
    "chartRepo": {
      "apiVersion": "app.alauda.io/v1beta1",
      "kind": "ChartRepo",
      "metadata": {
        "name": "test",
        "namespace": "cpaas-system",
        "labels": {
          "project.cpaas.io/catalog": "true"
        }
      },
      "spec": {
        "type": "Local",
        "url": null,
        "source": null
      }
    }
  }
}'

#2.6 Uploading the Chart

Upload the packaged chart to the repository:

curl -k --request POST \
--url https://$ACP_DOMAIN/catalog/v1/chartrepos/cpaas-system/test/charts \
--header 'Authorization:Bearer $API_TOKEN' \
--data-binary @"/root/charts/nginx-8.8.0.tgz"

#2.7 Uploading Related Images

1. Pull the image: podman pull nginx

2. Save as tar package: podman save nginx > nginx.latest.tar

3. Load and push to private registry:

   podman load -i nginx.latest.tar
   podman tag nginx:latest 192.168.80.8:30050/nginx:latest
   podman push 192.168.80.8:30050/nginx:latest

#2.8 Deploying the Application

Create Application resource via API:

curl -k --request POST \
--url https://$ACP_DOMAIN/acp/v1/kubernetes/$CLUSTER_NAME/namespaces/$NAMESPACE/applications \
--header 'Authorization:Bearer $API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "apiVersion": "app.k8s.io/v1beta1",
  "kind": "Application",
  "metadata": {
    "name": "test",
    "namespace": "catalog-ns",
    "annotations": {
      "app.cpaas.io/chart.source": "test/nginx",
      "app.cpaas.io/chart.version": "8.8.0",
      "app.cpaas.io/chart.values": "{\"image\":{\"pullPolicy\":\"IfNotPresent\"}}"
    },
    "labels": {
      "sync-from-helmrequest": "true"
    }
  }
}'

#2.9 Updating the Application

Update the application using PATCH request:

curl -k --request PATCH \
--url https://$ACP_DOMAIN/acp/v1/kubernetes/$CLUSTER_NAME/namespaces/$NAMESPACE/applications/test \
--header 'Authorization:Bearer $API_TOKEN' \
--header 'Content-Type: application/merge-patch+json' \
--data '{
  "apiVersion": "app.k8s.io/v1beta1",
  "kind": "Application",
  "metadata": {
    "annotations": {
      "app.cpaas.io/chart.values": "{\"image\":{\"pullPolicy\":\"Always\"}}"
    }
  }
}'

#2.10 Uninstalling the Application

Delete the Application resource:

curl -k --request DELETE \
--url https://$ACP_DOMAIN/acp/v1/kubernetes/$CLUSTER_NAME/namespaces/$NAMESPACE/applications/test \
--header 'Authorization:Bearer $API_TOKEN'

#2.11 Deleting the Chart Repository

curl -k --request DELETE \
--url https://$ACP_DOMAIN/apis/app.alauda.io/v1beta1/namespaces/cpaas-system/chartrepos/test \
--header 'Authorization:Bearer $API_TOKEN'

#3. Deploying Helm Charts as Applications via UI

#3.1 Workflow Overview

Add templates to manageable repositories → Upload templates → Manage template versions

#3.2 Prerequisites

Template repositories are added by platform administrators. Please contact the platform administrator to obtain the available Chart or OCI Chart type template repository names with Management permissions.

#3.3 Adding Templates to Manageable Repositories

1. Go to Catalog.

2. In the left navigation bar, click Helm Charts.

3. Click Add Template in the upper right corner of the page, and select the template repository based on the parameters below.

   Parameter	Description
   Template Repository	Synchronize the template directly to a Chart or OCI Chart type template repository with Management permissions. Project owners assigned to this Template Repository can directly use the template.
   Template Directory	When the selected template repository type is OCI Chart, a directory to store the Helm Chart must be selected or manually entered. Note: When manually entering a new template directory, the platform will create this directory in the template repository, but there is a risk of creation failure.

4. Click Upload Template and upload the local template to the repository.

5. Click Confirm. The template upload process may take a few minutes, please be patient.

   Note: When the template status changes from Uploading to Upload Successful, it indicates that the template has been uploaded successfully.

6. If the upload fails, please troubleshoot according to the following prompts.

   Note: An illegal file format means there is an issue with the files in the uploaded compressed package, such as missing content or incorrect formatting.

#3.4 Deleting Specific Versions of Templates

If a version of a template is no longer applicable, it can be deleted.

#Steps to Operate

1. Go to Catalog.

2. In the left navigation bar, click Helm Charts.

3. Click on the Chart card to view details.

4. Click Manage Versions.

5. Find the template that is no longer applicable, click Delete, and confirm.

   After deleting the version, the corresponding application will not be able to be updated.