Overview: 

The Auto-Deployer template is designed to facilitate the deployment of Helm charts by leveraging Helmfile. 

To pass the values entered in Addon Mart ConfigUI into our application we will utilize helmfile (with Jinja templates), that will act as Auto-Deployer template. Variable in our helmfile will be substituted by values from ConfigUI with help of Jinja templates.

Helmfile provides a declarative specification (helmfile.yaml) for deploying Helm charts. It allows defining Kubernetes resources and configurations in a single file, simplifying the management of those resources.

This approach simplifies the management of Kubernetes resources, making it easier to maintain, update, and scale applications.

This section walks through each component of the Auto-Deployer template, explaining its purpose and how it interacts with the deployment process.

It also highlights which parts of the template can be customized and which parts should remain unchanged.

Artifacts:

For the purpose of this tutorial we will be using this artifacts repository: https://gitlab.portaone.com:8949/read-only/tutorial-for-simple-application

Documentation Variables:

The documentation contains custom variables:

• <application_name>
• <vendor_name>

For details related to variables meaning, please refer => Guide to deploy application in Add-On Mart for third-party developers

Overview of Helmfile:

Helmfile is a tool that manages Helm charts by defining a declarative configuration for Helm releases. It allows specifying the desired state of Helm releases and the environments in which they should be deployed.

This tool is particularly useful for managing complex deployments with multiple Helm charts and environments.

Key Features of Helmfile:

• Declarative Configuration: Define the desired state in YAML files.
• Environment Management: Manage different configurations for multiple environments.
• Secrets Management: Securely manage sensitive data using external secret management tools.
• Atomic Upgrades: Ensure that deployments are fully applied or rolled back in case of failure.
• Chart Versioning: Easily specify and lock versions of Helm charts.

Helmfile Templates:

1. Template helmfile.yaml

The helmfile.yaml is the main configuration file used by Helmfile to manage Helm releases. It contains information about environments, default settings, repositories, and releases.

1.1 Content of helmfile.yaml:

{%- import "suspend_handler.jinja2" as suspend_handler -%}
{# ns from config.yaml as k8s.nameSpace #}
{#- env from config.yaml as k8s.env #}
{# instance_id from request params #}

environments:
  {@ env @}:
    values:
      - ipaas:
          ns: {@ ns @}
          context: {@ env @}
    secrets:
      - ../../../modules/repo/common/registry-secret.yaml

---
helmDefaults:
  wait: true
  historyMax: 3
  atomic: true
  timeout: 120
  createNamespace: false
  kubeContext: {@ env @}

commonLabels:
  service-name: ipaas

repositories:
  - name: ipaas
    url: registry.portaone.com/<vendor_name>/charts
    oci: true
    username: {{ .Values.registryK8sdeployer.user }}
    password: {{ .Values.registryK8sdeployer.password }}

releases:

  - name: <appplication_name>-{@ instance_id @}
    namespace: {@ ns @}
    installed: {@ installed @}
    chart: "ipaas/<appplication_name>"
    version: "{@ module_version @}"
    secrets:
      - tls-secret.yaml
    values:
      - app-conf.yaml
	  - app-secret.yaml
      - fullnameOverride: "<appplication_name>-{@ instance_id @}"
      - imagePullSecrets:
          - name: "{@ ns @}-env-secrets-k8s-deployer-registry"
      - ingress:
          enabled: {@ suspend_handler.is_ingress_enabled(state) @}
          class: "ipaas-ing"
          host: "{@ portal_domain @}"
          path: "/"
          tls:
            enabled: true
{%- if ssl_cert_auto %}
            secretAutoCreate: true
            certificateIssuerName: "lets-encrypt-{@ env @}-issuer"
{%- endif %}
            secret: "<appplication_name>-{@ instance_id @}-tls-secrets"
      - image:
          tag: "{@ module_version @}"
{%- if env == 'dev' %}
          pullPolicy: Always
{%- endif %}

1.2 Environments

Purpose: This section defines the different environments into which the application can be deployed. It specifies the configuration values and secrets specific to each environment.

Parameters:

• {@ env @}: The environment identifier, which is replaced by the actual environment name during deployment
• ns: The Kubernetes namespace where the application will be deployed.
• context: The Kubernetes context,.
• secrets: Path to the file containing sensitive data, such as registry credentials. This should not be modified.

Immutable Section: Should not be modified by the user. Contains references to registry secrets required for accessing the Harbor registry (registry used by Add-On Mart infrastructure. Images and Helm charts will be pushed to the Harbor registry during the deployment process to the TEAM).

environments:
  {@ env @}:
    values:
      - ipaas:
          ns: {@ ns @}
          context: {@ env @}
    secrets:
      - ../../../modules/repo/common/registry-secret.yaml

1.3 Helm Defaults

Purpose: Sets default options for all Helm releases specified in the Helmfile.

Parameters:

• wait: Ensures that Helm waits for the release to be deployed successfully before proceeding. This helps catch deployment errors early.
• historyMax: Limits the number of release versions stored, helping to manage disk space.
• atomic: Guarantees that all changes are rolled back if an error occurs during deployment.
• timeout: Sets a maximum time (in seconds) for any individual operation.
• createNamespace: Determines whether Helm should create the namespace if it doesn't exist. If set to false, the namespace must already exist.
• kubeContext: Specifies which Kubernetes context to use, ensuring the deployment targets the correct cluster and namespaces

Immutable Section: Should not be modified by the user.

helmDefaults:
  wait: true
  historyMax: 3
  atomic: true
  timeout: 120
  createNamespace: false
  kubeContext: {@ env @}

1.4 Common Labels

Purpose: Defines labels applied to all resources created by this Helmfile. These labels can be used for resource organization and filtering.

Parameters:

• service-name: A label applied to identify the service, which should remain ipaas as required by Add-On Mart. This should not be modified

Immutable Label: Required by Add-On Mart and should not be changed.

commonLabels:
  service-name: ipaas

1.5 Repositories

Purpose: Specifies the Helm chart repositories used in this Helmfile, allowing for the downloading of Helm charts from remote locations.

Parameters:

• name: The name of the repository, which identifies it within the Helmfile.
• url: The URL of the repository where the Helm charts are stored. Important: Replace <vendor_name> with the vendor name to access the specific repository. (Please contact PortaOne staff to obtain vendor access credentials for the TEAM service.)
• oci: Set oci:true  to enable OCI format support for helm charts storing.
• username and password: These are placeholders for the credentials required to access the repository. They are automatically filled in from values stored in registryK8sdeployer.

Modification Required: The vendor must update the URL to include their vendor name.

Immutable Configuration: Other values should remain unchanged (name, username, password).

repositories:
  - name: ipaas
    url: registry.portaone.com/<vendor_name>/charts
    oci: true
    username: {{ .Values.registryK8sdeployer.user }}
    password: {{ .Values.registryK8sdeployer.password }}

1.6 Releases

Purpose: Defines the individual Helm releases to be deployed, including their settings and configurations.

Parameters:

• name: The name of the release. You should replace <application_name> with your specific application's name, while keeping the {@ instance_id @} portion exactly as it appears in the example. The {@ instance_id @} is automatically handled for uniqueness, so you do not need to modify or append it manually. Just ensure that only your application’s name is substituted.
• namespace: The namespace where the release will be deployed. This should not be modified.
• installed: A boolean indicating whether the release should be installed.
• chart: The Helm chart to be used. Replace <appplication_name> with the application's chart name.
• version: The version of the Helm chart. This should not be modified.
• secrets: References to any secrets files used in the release, such as tls-secret.yaml.
• values: A list of additional configuration files or settings to override default values in the Helm chart.

Sub-Parameters:

• app-conf.yaml: A separate file for configuration values.
• fullnameOverride: Provides a custom name for the resources. It should include {@ instance_id @} for uniqueness.
• imagePullSecrets: Specifies secrets used to access private container registries.
• ingress: Configuration for the ingress controller, which manages external access to the application.
  • enabled: Determines whether the ingress is enabled, controlled by the suspend handler.
  • class: The class of the ingress controller used.
  • host: The host for the ingress, dynamically set by the Add-On Mart configuration UI.
  • path: The base path for the ingress.
  • tls: Configurations for TLS, allowing for secure connections. This includes options for auto-generating certificates with Let's Encrypt.
  • image: Contains details about the Docker image.
    • tag: The version of the Docker image to deploy. 
    • pullPolicy: Specifies when the image should be pulled. Set to Always in the development environment to ensure the latest image is used.

• appSecret: Configuration of the secret parameters that should be provided during application deployment 

Modification Required:  <application_name> should be substituted with the correct application name stated in Helm charts.

Immutable Configuration: ingress and imagePullSecrets configurations are integral to the Add-On Mart ecosystem and should not be altered.
The instance_id is critical for the deployment and should not be modified.

releases:

  - name: <application_name>-{@ instance_id @}
    namespace: {@ ns @}
    installed: {@ installed @}
    chart: "ipaas/<appplication_name>"
    version: "{@ module_version @}"
    secrets:
      - tls-secret.yaml
    values:
      - app-conf.yaml
      - fullnameOverride: "<application_name>-{@ instance_id @}"
      - imagePullSecrets:
          - name: "{@ ns @}-env-secrets-k8s-deployer-registry"
      - appSecret:
          secretUsername: "My secret username"
          secretPassword: "My secret password"
          secretBase64Encoded: "VGhpcyBzdHJpbmcgd2FzIGVuY29kZWQgdXNpbmcgYmFzZTY0"
      - ingress:
          enabled: {@ suspend_handler.is_ingress_enabled(state) @}
          class: "ipaas-ing"
          host: "{@ portal_domain @}"
          path: "/"
          tls:
            enabled: true
{%- if ssl_cert_auto %}
            secretAutoCreate: true
            certificateIssuerName: "lets-encrypt-{@ env @}-issuer"
{%- endif %}
            secret: "<application_name>-{@ instance_id @}-tls-secrets"
      - image:
          tag: "{@ module_version @}"
{%- if env == 'dev' %}
          pullPolicy: Always
{%- endif %}

2. Template tls-secret.yaml

The tls-secret.yaml file provides configurations for managing TLS certificates. It supports both user-provided certificates and auto-generated certificates using Let's Encrypt.

Purpose: To manage TLS certificates for securing application ingress points.

Parameters:

• crt and key: These fields store the TLS certificate and private key in Base64 format.
• ssl_cert_auto: A flag indicating whether to auto-generate certificates using Let's Encrypt. If true, certificates are generated automatically; otherwise, they must be provided by the user.

Dynamic Substitution: crt and key use module schema settings for substitution.

Immutable Configuration: This file should not be modified by the user as it adheres to Add-On Mart requirements.

Content of tls-secret.yaml:

{%- import "file_options.jinja2" as file_options -%}
ingress:
  tls:
{%- if ssl_cert_auto %}
    crt: ""
    key: ""
{%- else %}
    crt: {@ file_options.get_base64_data(portal_cert) @}
    key: {@ file_options.get_base64_data(portal_private_rsa_key) @}
{%- endif %}

3. Template app-conf.yaml

The app-conf.yaml file is used to override default values in the Helm chart's values.yaml file. It allows customization of application-specific settings using Jinja templates.

Purpose: Provides a mechanism to customize application settings during deployment, allowing for dynamic configuration based on instance-specific data.

Parameters:

• appConfig and appEnv: Sections that correspond to configurations defined in the Helm chart's values.yaml.
• serverUrl, configOption, customEnvVariable: Keys that override default values. These use Jinja templates, allowing for dynamic substitution based on the instance configuration.

Dynamic Substitution: Each configuration item in app-conf.yaml uses {@ setting_id @} placeholders to dynamically replace values during deployment. The setting_id corresponds to the id in the module schema.

Customization: This file can be extended if needed if we want to pass additional values. Additional keys can be added or existing ones overridden as defined in the Helm chart's values.yaml.

Content of app-conf.yaml:

appConfig:
  serverUrl: "{@ server_url @}"
  configOption: "{@ config_option @}"

appEnv:
  customEnvVariable: "{@ custom_env_variable @}"

Summary of Modifiable Sections:

Here is a summary table indicating which sections of the Auto-Deployer template can be modified and which should remain unchanged:

Summary:

The Auto-Deployer template provides a robust framework for managing Kubernetes deployments using Helmfile.

 By following this guide, it is possible to effectively configure and deploy applications while ensuring compliance with the Add-On Mart ecosystem requirements.

The template is designed with flexibility in mind, allowing for customization where indicated while maintaining critical components unchanged to ensure compatibility and functionality.