Creating Helm chart Releases

There are two ways you can create Product Releases in Apollo:

• Follow the Product publishing workflow
• Use the Apollo CLI

Product publishing workflow

1. Navigate to the Products page in Apollo and select the Helm chart Product you want to create a Release for.

2. Select Create new Release. The Release creation form opens with the Group ID and Artifact ID fields pre-filled from the Product's metadata.

3. In the Release version field, enter the version number for this Release. Versions must follow semantic versioning format (for example, 1.2.3 or 1.2.3-rc1).

4. Under Product type, select Helm chart.

5. Under Publish type, select whether the chart is hosted in an OCI repository or a Helm repository.

6. Complete the remaining fields:

• In Helm chart name, enter the name of the chart as it appears in the repository (for example, wordpress).

• In Helm chart version, enter the version of the chart as it appears in the repository (for example, 13.1.4).

• In Helm repository URL, enter the URL of the repository hosting the chart:

  • For OCI repositories, the URL must begin with oci:// (for example, oci://docker.example.com/charts).
  • For Helm repositories, the URL must begin with https:// (for example, https://charts.bitnami.com/bitnami).

• Optionally, in OCI artifacts, add one or more OCI artifact URIs that Apollo should associate with this Release (for example, docker.example.com/charts/my-chart:1.0.0).

7. Select Create release.

After the Release is created, a confirmation message appears. Select View Product Release to navigate to the new Release's detail page.

Use the Apollo CLI

Prerequisites

• You should download and set up the Apollo CLI.
• An existing Helm chart, located in a Helm chart repository of your choice.
• An Apollo Bearer Token or a client ID and client secret for authentication.
• A reference to your Helm chart repository. For the purposes of this documentation, we will be using Bitnami and can apply the following secrets via kubectl. Note that the namespace in the secrets needs to be the same as the namespace where the Helm charts will be installed.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
# secret for docker.io registry
apiVersion: v1
kind: Secret
metadata:
  labels:
    apollo.palantir.com/artifact-store: "docker.io"
  name: docker-io-registry
  namespace: default
stringData:
  # the following two methods can be provided for auth:
  #   username/password auth
  #   note: username must be provided if and only if password is provided.
  username: <username>
  password: <password>
  #   cert auth
  #   note: cert must be provided if and only if key is provided.
  cert: <PEM encoded bytes>
  key: <PEM encoded bytes>
  ca: <PEM encoded bytes>
type: Opaque
---
# secret for bitnami image repository
apiVersion: v1
kind: Secret
metadata:
  labels:
    apollo.palantir.com/artifact-store: "charts.bitnami.com"
  name: bitnami-repository
  namespace: default
stringData:
  # the following two methods can be provided for auth:
  #   username/password auth
  #   note: username must be provided if and only if password is provided.
  username: <username>
  password: <password>
  #   cert auth
  #   note: cert must be provided if and only if key is provided.
  cert: <PEM encoded bytes>
  key: <PEM encoded bytes>
  ca: <PEM encoded bytes>
type: Opaque

Package a Helm chart for Apollo

Apollo thinks of the software it manages as Products. To package an existing Helm Chart for Apollo, we will need to do the following:

• Create an Apollo Product tarball
  • This Product tarball will also contain metadata that tells Apollo which group, Product and version this application belongs to.
• Publish your Product tarball with Apollo

For this example, we’ll be considering Wordpress, a popular open-source content management system.

Create an Apollo Product tarball

An Apollo Product tarball can be created either within your repository if you’re deploying your own application or can be created separately if you’re taking a public image (as we’re doing here).

For Helm charts, the layout for an Apollo Product tarball looks as follows:

wordpress-0.0.0-88-g70e29b2
├── deployment            # Required Apollo metadata
  └── manifest.yml        # URL of associated container image(s) are included here

All of our files are contained in a directory named wordpress. The deployment/manifest.yml file contains metadata required by the Apollo platform; this file should contain the following:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
manifest-version: "1.0"
product-group: <group ID>
product-name: <product name>
product-version: <version> # This version is used for downloading the artifact
                           # It can be distinct from the Helm Chart version,
                           # but it's recommended to keep them the same.
product-type: helm-chart.v1
extensions:
  helm-chart:
    helm-chart-name: <name of helm chart in the helm chart repo>
    #will be used to preset the version in the Apollo Control Center
    helm-chart-version: <version of the helm chart>

The group ID, Product name, and version should be carefully chosen; they will be used to construct an Apache Maven coordinate and the product-version field must be an Apollo orderable version (see Products, Versions, and Releases for more details). Note that this is slightly more restrictive than Semantic Versioning but required for Apollo to coordinate upgrades of your Product.

The apollo-cli can be used to create Apollo Product tarballs. The following command creates a TGZ that contains the expected manifest:

product-release helm-chart init --as-tgz --maven-coordinate=[maven-coordinate] --repository-url=[helm-repository-url] --name=[helm-chart-name] --version=[helm-chart-version]

Here is an example invocation:

Copied!
1
./apollo-cli product-release helm-chart init --as-tgz --maven-coordinate="com.palantir.example:wordpress:13.1.4" --repository-url="https://charts.bitnami.com/bitnami" --name=wordpress --version=13.1.4

If a valid manifest file already exists, the product-release init --manifest-file=[manifest-file] command can be used to create a product tarball that has the manifest in the proper location. Here is an example invocation (assuming that there is a valid manifest.yml file in the working directory):

Copied!
1
./apollo-cli product-release init --manifest-file=manifest.yml

Setting dependencies across Product Releases

Apollo’s first-class concept of Product dependencies ensures that upgrades only happen when all the required pre-requisites (that is, dependencies) are met, and obligations to consumers are maintained.

This allows fast-moving Product Teams to release software independently, without having to sequence or coordinate upgrades with other Product Teams.

Product dependencies are embedded in the manifest of the Product Release in the extensions section under the product-dependencies.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
extensions:
  product-dependencies: # An unordered list of product dependencies
     # (required) The dependency's product-group (as per its manifest)
   - product-group: <group ID>
     # (required) The dependency's product-name (as per its SLS manifest)
     product-name: <product name>
     # (required) An orderable version indicating the lowest allowed
     # version (inclusive) for this dependency
     minimum-version: <min version>
     # (required) A version matcher indicating the highest allowed
     # version (inclusive) for this dependency
     maximum-version: <max version>
     # (optional) An orderable version indicating the recommended version
     # for this dependency. If omitted, this will be equal to the minimum-version
     recommended-version: <recommended version>
     # (optional) Whether the dependency is optional. Defaults to false.
     optional: false

Example for a populated manifest for an example helm-charts product:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
manifest-version: '1.0'
product-group: com.palantir.example
product-name: wordpress
product-version: 13.1.4
product-type: helm-chart.v1
extensions:
  helm-chart:
    - helm-chart-name: wordpress
      helm-chart-version: 13.1.4
  product-dependencies:
    - product-group: com.palantir.foo
      product-name: foo
      minimum-version: 1.3.5
      maximum-version: 1.x.x
      optional: false
    - product-group: com.palantir.bar
      product-name: bar
      minimum-version: 2.7.0
      maximum-version: 2.x.x
      optional: true

Optional dependencies

To learn more about how to interact with optional dependencies, see Apollo Product Spec - Product Dependencies.

Artifacts Manifest extension

If you have vulnerability scanning is enabled on your Apollo Hub, you must indicate to Apollo what container images are used in your Helm Chart. You can do this using the artifacts manifest extension. To learn more, see Container image specification.

Access token

You will need either a Bearer Token or a client ID and client secret to publish Products using the Apollo CLI.

Learn more about configuring authentication for the Apollo CLI.

Publish your Helm Chart to Apollo

Once your Helm Chart has been packaged, it can be published to Apollo using the apollo-cli; you will need the access token for authentication.

The following command creates and publishes the Helm chart artifact using the specified parameters:

publish --apollo-url=[url] --apollo-token=[token] helm-chart --maven-coordinate=[maven-coordinate] --helm-repository-url=[helm-repository-url] --helm-chart-name=[chart-name] --helm-chart-version=[chart-version]

The following command creates and publishes the Helm chart artifact using a client ID and client secret for authentication:

publish --apollo-url=[url] --apollo-client-id=[client-id] --apollo-client-secret=[client-secret] helm-chart --maven-coordinate=[maven-coordinate] --helm-repository-url=[helm-repository-url] --helm-chart-name=[chart-name] --helm-chart-version=[chart-version]

Here is an example invocation:

Copied!
1
./apollo-cli publish --apollo-url="$APOLLO_URL" --apollo-token="$APOLLO_TOKEN" helm-chart --maven-coordinate="com.palantir.example:wordpress:0.0.0-88-g70e29b2" --helm-repository-url="https://charts.bitnami.com/bitnami" --helm-chart-name=wordpress --helm-chart-version=13.1.4

If an Apollo artifact TGZ already exists locally, it can be published using the command publish --apollo-url=[url] --apollo-token=[token] artifact --product-tgz=[artifactPath].

Here is an example invocation:

Copied!
1
./apollo-cli publish --apollo-url="$APOLLO_URL" --apollo-token="$APOLLO_TOKEN" artifact --product-tgz=wordpress-13.1.4.helmchart.config.tgz

If a manifest file exists locally, the following command can be used to publish the product for that manifest:

publish --apollo-url=[url] --apollo-token=[token] manifest --manifest-file=[manifestPath]

Here is an example invocation:

Copied!
1
./apollo-cli publish --apollo-url="$APOLLO_URL" --apollo-token="$APOLLO_TOKEN" manifest --manifest-file=manifest.yml`

This CLI can be easily incorporated into your CI process to publish future versions of your Helm Chart.