How to add and maintain App in an App Catalog
Table of Contents
- Table of Contents
- The workflow process
- 1. Creating repository structure
- 2. Providing chart sources
- 3. Ensuring quality of the chart
- 4. Making the chart available in an app catalog
- 5. Building, validating and testing the chart
- 6. Add your repository to
giantswarm/githuband “Changes and Releases”
- 7. Releasing the App in Giantswarm Catalog
- Related documentation
This document is meant to be a comprehensive guide and description of the process we use to maintain and release managed apps. The idea is that you should use this process by default and it fits 90% of use cases. For the other 10%, common sense applies, as for the first 90% as well :)
In the App Platform, Apps are defined as Helm chart packages. App Catalogs are stored as Helm repositories. Packaging and pushing Apps into an App Catalog is automated using CircleCI and architect orb’s push-to-app-catalog job.
For an overview of the App Platform, Apps, and App Catalogs, please read The Giant Swarm App Platform
The workflow process
Our apps are currently based on Helm charts only. Here’s how we work on an app, from the very beginning to making a release.
1. Creating repository structure
This part of work involves following steps:
- creating and setting up a new repository for an application
- please fork the https://github.com/giantswarm/template-app
- now either:
- getting sources from an upstream project, making required changes and maintaining it
- writing chart from scratch
Check below for more details about the bullets above.
1.1. Create and configure a repo for the App
-appsuffix should be in the repository name. Everywhere else, omit
Use the following template repo to generate the basic skeleton for your app’s repo: https://github.com/giantswarm/template-app.
- Go to https://github.com/giantswarm/APP-NAME-app/settings and make sure
Allow merge commitsbox is unchecked and
Automatically delete head branchesbox is checked.
- Go to https://github.com/giantswarm/APP-NAME-app/settings/access and add
Note: By convention, we name app repos
[APP-NAME]-app. Adding the topic
app to the GitHub repository is also useful. This helps the user distinguish the type of repo.
However, it is no longer required nor advisable to name your app and helm chart (step 2 & 3 below) with the
-app suffix for default apps installed as part of a release require
>= v3.5.1 on AWS or
>= 0.23.21 on Azure and KVM.
AWS >= 13.1.0 Azure >= 14.0.2 KVM >= 13.1.0
myexample app, the app’s name is
myexample and the repo is
If you need a Go project skeleton, start with this template instead: https://github.com/giantswarm/template.
2. Providing chart sources
2.1. Getting the sources from upstream
This is the most frequent (so far: only) use case. The hard part is to be able to easily synchronize with upstream sources while also keeping our local changes. Please read our guide about it: how to track upstream repositories using the git-subtree method.
2.2. Writing a chart from scratch
This includes a rare situation when there’s no upstream chart for the app we want. So far, it didn’t actually happen.
3. Ensuring quality of the chart
When we provide a chart, we want to be sure that some best practices are met to avoid problems we have already seen in the past. The list of these practices is below.
3.1. Providing all the necessary data and metadata in
We extensively use
Chart.yaml properties to provide information about the chart to our platform
and thus our users. Please make sure to check this sample
for an example of what we expect to be provided in the
Chart.yaml. Please note, that if you’re using
abs (see below) to build your chart, our annotations
will be automatically set for you.
If you fail to set the supported properties, the generated metadata won’t contain information that can help users deploy and configure the app.
For basic properties listen in
Chart.yaml, remember to:
Chart.yamlhas all required fields, including
appVersionwhich is usually optional. See: https://helm.sh/docs/topics/charts/.
Chart.yamlhas all fields needed so the app displays nicely in Happa.
- If your templates contain empty values (i.e not defined with defaults in
values.yaml), you can provide multiple value files for validation by creating yaml files (
helm/[APP-NAME]/ci. For an example, see the pull request #42 for
3.2. Retagging and copying images to our registries
To avoid problems when upstream registries are down or when our apps are deployed to China, we use our own image registries and you need to copy any upstream images used to our repos. To do that, we have the retagger tool. Add your images to the config file in its repo, push the changes and the images will be synchronized for you.
More information about our registries can be found below:
3.3. Adjust chart for custom image registries
Because images are held in other registries than upstream, we have to account for that in the
values.yaml configuration file. It is important to keep this configuration format, because the
registry part of it is set automatically to the best registry depending on installation’s location
(Aliyun in China, Quay elsewhere).
values.yaml should have the following top-level section:
image: registry: quay.io repository: giantswarm/my-app tag: 0.1.1
You need to use these values in the chart to configure images for Deployments and such.
3.4. Providing validation schema for
We provide a YAML schema for validating
values.yaml file that is provided at installation time
by a user. That way we can prevent the user from a wide range of typos and misconfiguration errors.
Our detailed documentation about generating the schema is available on the intranet
3.5. The quality bars checklist
For charts we support for our customers, we have additional “quality bar” checklists. Please note, that currently they need a revamp and you should them as suggestions, not hard requirements. Still, please run the checklists before you publish a chart.
4. Making the chart available in an app catalog
More detailed information about how to push app to app-catalog is available on the intranet.
The very minimal circle CI configuration file that does the job using
abs (see below)
looks like this:
version: 2.1 orbs: architect: email@example.com workflows: package-and-push-chart-on-tag: jobs: - architect/push-to-app-catalog: context: "architect" executor: "app-build-suite" name: "package and push loki chart" app_catalog: "giantswarm-catalog" app_catalog_test: "giantswarm-test-catalog" chart: "YOUR_CHART" # Trigger job on git tag. filters: tags: only: /^v.*/
Personalize the README and CircleCI config with your app’s name. For enabling CircleCI builds, check the CircleCI Intranet page.
Find the latest
ARCHITECT_ORB_VERSION here: https://circleci.com/orbs/registry/orb/giantswarm/architect, then update the CircleCi config with it.
push-to-app-catalog jobs to your needs:
chartparameter to reflect the chart name. For
myexampleit has to be
- If adding App to a different App Catalog, change target
If you want automatic metadata generation, set
executor: "app-build-suite" (see <#building-validating-and-testing-the-chart>) in the
push-to-app-catalog CircleCI configuration (
architect-orb docs). This packages your new app with
app-build-suite, enabling metadata integration and packaging (Spec and more information about metadata).
You’ll need to modify the
main.yaml in the
.abs/ directory to match your desired
app-build-suite configuration options.
helm/APP-NAME directory with your app’s name, then add your Helm chart to this directory.
With the default CircleCI project setup from the template-app, commits to branches will trigger the build. If successful, a chart package will be pushed to giantswarm-playground-test-catalog.
- Test Catalogs are not exposed to customers.
- Our API does some caching - it takes a few minutes for new releases to show up in Happa
5. Building, validating and testing the chart
In order to make the application build process more streamlined and repeatable across developer’s
desktop and CI/CD systems, we have created app-build-suite (a.k.a.
6. Add your repository to
giantswarm/github and “Changes and Releases”
Open a PR in giantswarm/github to add your repository to
flavour is set to
app (the required value for repositories which contain just a Helm chart). This ensures certain files are kept in sync across our repos. Once merged,
architectbot will open a PR in your repository to add the necessary files.
7. Releasing the App in Giantswarm Catalog
In order to include your App in the Giantswarm catalog, you need to create a release.
Please follow How to release a project in order to do that.
- A lot of more detailed processes are documented already on the handbook
- Adding Readmes and Icons to Apps in Happa describes the process of adding a Readme and an app icon to your new app
- Quality bars for Managed Apps contain hints how to make your app fit for being a managed app
- Kubernetes Annotations and Labels in
giantswarm/fmtcontain some commonly used annotations and labels in kubernetes resources
- App Release Checklist contains hints and guidelines on what to do when releasing any Managed App
- Creating container registries for retagger
- CircleCI Intranet page
- MatchLabels are immutable