Install Platform Base

This page takes you from an empty cluster to Argo CD running and syncing the Platform Base Applications. Check the requirements first.

The result is a Git repository with this layout:

vendir.yml
vendor/                  # Platform Base, fetched by vendir
cluster/
  config.libsonnet       # your configuration
  main.jsonnet           # the entry point Argo CD renders

1. Vendor Platform Base

Add Platform Base to vendir.yml in your repository, with ref set to a released tag:

apiVersion: vendir.k14s.io/v1alpha1
kind: Config
directories:
- path: vendor
  contents:
  - path: github.com/RocketPadPlatforms/base
    git:
      url: https://github.com/RocketPadPlatforms/base.git
      ref: vX.Y.Z # pin to a released tag
    excludePaths:
    - .git/**/*

Fetch it:

vendir sync

Commit vendor/ and vendir.lock.yml. Argo CD renders from your repository, and Platform Base brings its own third-party dependencies in deps/vendor/, so everything has to be in Git.

2. Write the configuration

Create cluster/config.libsonnet with your base domain. baseDomains is the only mandatory option:

{
  baseDomains: ['example.com'],
}

Create cluster/main.jsonnet, the entry point that combines your configuration with Platform Base:

local apps = import '../vendor/github.com/RocketPadPlatforms/base/apps.libsonnet';
local path = import '../vendor/github.com/RocketPadPlatforms/base/deps/vendor/gitlab.com/rocketpadplatforms/platform/util-libsonnet/util-libsonnet/path.libsonnet';
local rootApp = import '../vendor/github.com/RocketPadPlatforms/base/root.libsonnet';
local config = import './config.libsonnet';

function(root=false, repoURL, revision='HEAD', pathPrefix='cluster', dynamicConfig={})
  local appsInstance = apps(
    repoURL,
    revision,
    (path.new(pathPrefix) + path.join('../vendor/github.com/RocketPadPlatforms/base')).path,
    dynamicConfig=config + dynamicConfig,
  );

  if root then
    appsInstance.bootstrap + [rootApp(repoURL=repoURL, revision=revision, path=pathPrefix, dynamicConfig=dynamicConfig)]
  else
    appsInstance.flattened

The function has two modes, selected by root:

• root=true renders the bootstrap: Argo CD itself and one bootstrap Application. You apply it once by hand.
• root=false renders the Argo CD Applications of all components. The bootstrap Application syncs this from Git.

Argo CD passes repoURL, revision and pathPrefix to main.jsonnet itself, so the Applications always point back at your repository.

To change an option, add it to config.libsonnet. Use +: for nested options, for example observability+: { profile: 'singleNode' }. A plain field replaces the whole object, including defaults you did not mean to change. The configuration schema in vendor/github.com/RocketPadPlatforms/base/config.libsonnet lists every option with its default.

Commit cluster/ and push it to the repository that Argo CD will read.

3. Give Argo CD access to a private repository

Skip this step if the repository is public. Otherwise enable argocd.platformRepoCreds so the bootstrap includes a repository credentials Secret for the address you render with in step 4:

Field	Default	Meaning
enabled	false	Create the credentials Secret.
username	null	User name, required with password.
password	null	Password or access token.
sshPrivateKey	null	SSH private key, used instead of user name and password.
insecure	false	Written to the Secret as its insecure field.

Pass the values when you render the bootstrap in step 4 instead of committing them. Add this argument to the jsonnet command:

--tla-code dynamicConfig='{ argocd+: { platformRepoCreds+: { enabled: true, username: "git", password: "<token>" } } }'

warning

On a private repository without credentials, Argo CD cannot clone it: the bootstrap Application shows an error and no other Application appears. With credentials, they are also stored in the spec of Argo CD Application objects, where anyone who can read Applications can see them. Use a token with read access to this repository only.

4. Render and apply the bootstrap

Render the bootstrap with the address of your repository, the branch or tag Argo CD follows, and the directory of main.jsonnet:

jsonnet --yaml-stream \
  --tla-code root=true \
  --tla-str repoURL=https://git.example.com/acme/cluster.git \
  --tla-str revision=main \
  --tla-str pathPrefix=cluster \
  cluster/main.jsonnet | grep -v '^\.\.\.$' > bootstrap.yaml

The grep removes the end-of-stream marker that jsonnet appends. Do not commit bootstrap.yaml, it can contain the credentials from step 3.

Apply it with server-side apply, because some Argo CD CRDs are too large for a client-side apply:

kubectl apply --server-side -f bootstrap.yaml

If kubectl reports that it cannot find the Application kind, wait a few seconds for the CRDs and run the same command again.

5. Wait for the Applications

The bootstrap Application syncs cluster/main.jsonnet with root=false and creates one Application per component (see Architecture). Follow them with:

kubectl -n argocd get applications

There are no sync waves. An Application whose dependencies are not ready yet can fail a sync, and Argo CD tries again on its next reconciliation (about every three minutes). The cluster therefore needs some time to converge. If an Application stays unhealthy, see Troubleshooting.

6. Open Argo CD

Open https://argocd.<baseDomain> and sign in as admin. Read the initial password from the cluster:

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath='{.data.password}' | base64 -d

Without DNS records, forward the port and open http://localhost:8080. Argo CD serves plain HTTP behind the ingress (server.insecure is TRUE):

kubectl -n argocd port-forward svc/argocd-server 8080:80

Platform Base issues a self-signed certificate by default, so browsers warn about https://argocd.<baseDomain> until you switch to ACME.