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

Getting started

If you are getting started with Apollo and recently created a new Environment, you can select Publish your own product from the Overview tab of the Environment page.

Step 1: Download the Apollo CLI

You will be prompted to download and configure the Apollo CLI. You should download the Apollo CLI in a safe folder on your machine, such as Downloads. Then, run the command chmod +x ~/Downloads/apollo-cli to turn the Apollo CLI into an executable. After you are finished, select I have downloaded the CLI to continue.

Step 2: Complete the Product registration form

Then you can fill out the Product publishing form, which Apollo will use to generate a command to publish your Product.

Prerequisites

Before completing the rest of the workflow, make sure you have installed and are familiar with the Helm CLI.

Example: Wordpress

For the sake of this walkthrough, we are going to publish the newest version of the wordpress Helm chart from the bitnami repository to Apollo.

1. Confirm that you have Helm installed by running the command helm version in your terminal.
2. Confirm that you have initialized the bitnami repository by running the command helm repo list in your terminal.
   • If the bitnami repository does not appear, you can run the command helm repo add bitnami https://charts.bitnami.com/bitnami to add it to your local Helm installation.
3. Determine the Helm chart you want to install. For this example, we want to install wordpress. To list all available Helm charts, you can run the command helm search repo.

After selecting the Helm chart we want to install, we can begin to complete the form:

4. Artifact ID: The Artifact ID is a field that you define that is used to name the Product you will publish. For our example, we will use the Artifact ID wordpress.
5. Group ID: The Group ID is another field that you define. The Group ID allows Apollo to organize many Products into distinct groups. For our example, we will use the Group ID palantir.

6. Publish Type: The type of Product you want to publish, which you can select using the dropdown. For our example, we will keep the default value Helm Chart because we are publishing a new Helm chart.
   • Helm Chart: Publish a Helm chart.
   • Artifact: Publish a Product that you have stored locally on your machine that is not containerized.
7. Search for the chart information for the Helm chart you want to install by running the helm search repo <keyword> command. Because we are installing wordpress, we run the command helm search repo wordpress:

$ helm search repo wordpress
NAME              CHART VERSION  APP VERSION  DESCRIPTION
bitnami/wordpress 17.1.8         6.3.1        WordPress is the world's most popular blogging ...

8. Helm Chart Name: The name of the Helm chart within the repository, which can be found in the output from the helm search repo <keyword> command. From the output above, we get the value bitnami/wordpress under the NAME column. When completing the Product publishing form, be sure to enter the value after the /, which is wordpress in this example.
9. Helm Chart Version: The version of the Helm chart to publish, which can be found in the response from the helm search repo <keyword> command. In the example above, the Helm chart version is 17.1.8. Be sure that you use the value in the CHART VERSION column and not the APP VERSION.
10. Helm Chart Repository URL: The URL where the Helm chart is hosted. Apollo uses this URL along with the chart name and version to locate and download the Helm chart. You can run the helm repo list command to find the repository URL. In our example, the value is https://charts.bitnami.com/bitnami.

$ helm repo list
NAME     URL
bitnami  https://charts.bitnami.com/bitnami

After you have completed the above steps, use the information to fill out the form. The completed form for our example looks like:

Step 3: Publish your Product

In the previous step, Apollo generated a command to Publish your product.

Copy the command and run it in the directory that you installed the Apollo CLI in. After the command has completed, you can select Go to new product to view the Product.

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’ll 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:

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:

create-product-tgz helm-chart --maven-coordinate=[maven-coordinate] --helm-repository-url=[helm-repository-url] --helm-chart-name=[helm-chart-name] --helm-chart-version=[helm-chart-version]

Here is an example invocation:

./apollo-cli create-product-tgz helm-chart --maven-coordinate="com.palantir.example:wordpress:13.1.4" --helm-repository-url="https://charts.bitnami.com/bitnami" --helm-chart-name=wordpress --helm-chart-version=13.1.4

If a valid manifest file already exists, the create-product-tgz manifest --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):

./apollo-cli create-product-tgz manifest --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.

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:

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.

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.