Installation

In order to run our Rocket Pad Platform you need access to one of the supported Infrastructure as a Service providers like Amazon Web Services, Hetzner or on bare metal. To check if your desired IaaS provider is supported check te list below. With a supported IaaS our platform will be able to bootstrap automatically due to Infrastructure as Code (IaC) Modules created for every supported IaaS provider.

Supported Rollout targets

Prerequisites

Git Repository (e. g. a GitHub or Gitlab project)
A running Kubernetes cluster
- Optional IaC Bootstrap:
- You can also use our IaaS provider IaC Modules to bootstrap from just an cloud provider account
- Or in case of Bare metal: VMs with talos Nodes in maintenance mode

Tools

Jsonnet
OpenTofu or Terraform (for IaC only)

Kubernetes Cluster Requirements

The underlying Infrastructure or your running Kubernetes Cluster has to meet the following hardware requirements:

Cluster

Resource	Minimum	Recommended
Number of Nodes	1 Nodes	3 Nodes
CPU Cores	8 Cores	12 Cores
Memory	24GB	32GB

Nodes

Resource	Minimum	Recommended
CPU Cores	4 Cores	6 Cores
Memory	4GB	16GB
Boot Disk	64GB	512GB

The size of the boot disk also depends on the storage system. If the cluster is using the boot disk as application state storage or as database storage, the size must be increased accordingly.

Preparing a Platform Git Repository

We encourage and recommend highly to use our platform with GitOps principles in mind. Our platform is build around GitOps and optimized for being fully configurable trough code and self updating whenever configuration code changes in a platform relevant git repository. Therefor the first step is to create a new Git Repository from which our platform can be bootstrapped with your individual configuration.

The following needs to be setup:

Git repository for platform bootstrapping
Load Rocket Pad Platform code into a /deps folder
Create a bootstrap folder
Add bootstrap Jsonnet files
Add your bootstrap apps
Configure your custom Rocket Pad Platform
Load the Terraform module matching your IaC provider in the repo
Setup a Terraform state and initialize terraform

We recommend a folder structure in your Rocket Pad Platform bootstrap repository as follows:

/
- deps/ Location of the dependencies managed using jsonnet-bundler
- iac/ Location of the infrastructure as code
- bootstrap/ Location of the platform configuration files (jsonnet)

2. Load Rocket Pad Platform code

In order to bootstrap the Rocket Pad Platform our platform code can be directly served from your repository. Due to the Rocket Pad Platform being open source you can load the full codebase into your repository and have full control over it.

For our terraform modules to work out of the box it is recommended to create the folder /deps in the /root of the repository and copy our platform base /deps code into that folder. The Rocket Pad Platform base code can be found on Gitlab.

3. Bootstrap folder

The /deps folder provides the platform code and its dependencies. But for custom bootstrap configuration we will need to create another folder /bootstrap. In this folder create a folder /bootstrap/apps. This will be the folder where your first Argocd apps will go. We recommend using the App Of Apps Pattern and just add one app there to apply other apps in a separate repository.

Now add the following files to the bootstrap folder:

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

patches.jsonnet
function(dynamicConfig={})
  (import '../deps/vendor/gitlab.com/rocketpadplatforms/platform/provider/talos/patches.libsonnet')(dynamicConfig + import './config.libsonnet')

main.jsonnet
local platformApps = import '../deps/vendor/gitlab.com/rocketpadplatforms/platform/base/apps.libsonnet';
local rootApp = import '../deps/vendor/gitlab.com/rocketpadplatforms/platform/base/root.libsonnet';
local providerApps = import '../deps/vendor/gitlab.com/rocketpadplatforms/platform/provider/talos/apps.libsonnet';
local providerApp = import '../deps/vendor/gitlab.com/rocketpadplatforms/platform/provider/talos/root.libsonnet';
local config = import './config.libsonnet';

local argocd = import '../deps/vendor/github.com/jsonnet-libs/argo-cd-libsonnet/2.7/main.libsonnet';
local path = import '../deps/vendor/gitlab.com/rocketpadplatforms/platform/base/deps/vendor/gitlab.com/rocketpadplatforms/platform/util-libsonnet/util-libsonnet/path.libsonnet';
local util = import '../deps/vendor/gitlab.com/rocketpadplatforms/platform/base/deps/vendor/gitlab.com/rocketpadplatforms/platform/util-libsonnet/util-libsonnet/util.libsonnet';
local app = argocd.argoproj.v1alpha1.application;

function(root=false, repoURL='ADDRESS_TO_YOUR_GIT_REPOSITORY', revision='HEAD', pathPrefix='./bootstrap', dynamicConfig={})

  local apps = {
    platform: platformApps(repoURL, revision, (path.new(pathPrefix) + path.join('../deps/vendor/gitlab.com/rocketpadplatforms/platform/base/')).path, dynamicConfig=dynamicConfig) {
      config+: config + dynamicConfig,
    },
    provider: providerApps(repoURL, revision, (path.new(pathPrefix) + path.join('../deps/vendor/gitlab.com/rocketpadplatforms/platform/provider/talos/')).path, dynamicConfig=dynamicConfig) {
      config+: config + dynamicConfig,
    },

  };

  if !root then
    apps.platform.flattened
    + apps.provider.flattened
    + [
      std.parseYaml(importstr 'apps/app-of-apps.yaml'),
    ]
  else
    apps.platform.bootstrap
    + [rootApp(repoURL=repoURL, revision=revision, path=pathPrefix, dynamicConfig=dynamicConfig)]

Do not forget to add the git address of the bootstrap repository you setup at step 1 in the main.jsonnet file as replacement for 'ADDRESS_TO_YOUR_GIT_REPOSITORY'.

The config.libsonnet file is where you can add your additional configuration for the Rocket Pad Platform . Take a look into the config.libsonnet file in our RPP Base Repo in order to find out what can be configured (Detailed documentation about configuration will be added).

Now add the /bootstrap/apps/app-of-apps.yaml file in order to get the App Of Apps Pattern running on bootstrap:

/bootstrap/apps/app-of-apps.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: app-of-apps
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  sources:
    - repoURL: <ADDRESS_TO_YOUR_GITOPS_REPOSITORY>
      targetRevision: HEAD
      path: apps/

  destination:
    server: 'https://kubernetes.default.svc'
    namespace: argocd
  syncPolicy:
    syncOptions:
      - CreateNamespace=true
    automated:
      prune: true
      selfHeal: true

Now your Rocket Pad Platform can be bootstrapped.

6. (Optional no IaC Module) Bootstrap on already existing Kubernetes Cluster

No Kubernetes Cluster? No Problem

In case you don't have an empty cluster running that you want to use for the Rocket Pad Platform and want to create a cluster from IaC in one of our supported cloud providers or deploy a cluster with talos on bare-metal infrastructure jump to the next step and ignore this one.

If there is already a Kubernetes Cluster available to rollout the Rocket Pad Platform on it you can do this by using Jsonnet directly to apply the /bootstrap folder we created earlier:

cd bootstrap
jsonnet main.jsonnet | kubectl apply -f -

7. (Optional IaC Module) Terraform IaC based bootstrap

In case you want to bootstrap the infrastructure below kubernetes as well you can use a cloud provider or bare metal nodes / vms. If there is a cloud provider available to bootstrap the Rocket Pad Platform on then get the terraform code example from our Bootstrap IaC example repository. Copy the desired example folder over to your bootstrap repository in a new folder named /iac.

You can follow the instructions within the example folder to set everything up. In a general sense most of the time the setup looks like this:

Setup your terraform state backend
Initialize backend with terraform init
Run a terraform plan
Apply the terraform plan
Export kubeconfig from terraform outputs
Use kubectl get nodes to verify a successful cluster setup

Add sensitive config

In order to add sensitive config values to the config that was created in step 3 inside the bootstrap folder create a dynamic-config.libsonnet file within the iac folder. You can overwrite any configuration from here. We recommend using this file only for overwriting sensitive config values.

warning

Exclude the dynamic-config.libsonnet file from git using .gitignore.

To overwrite config values from this file you need to add the file as an import to the input variables to terraform. This can by done in a .tfvars file. In this example we use local.tfvars. In this file add the following variable line:

local.tfvars*

bootstrap_dynamic_config = "(import 'config.libsonnet')"

This will load the config.libsonnet file into a input variable to the terraform IaC script and from there overwrite or add values within the /bootstrap/config.libsonnet when running terraform plan -var-file="local.tfvars" -out tfplan.

Example with Gitlab for Terraform state

cd ./iac

export GITLAB_ACCESS_TOKEN=YOUR-ACCESS-TOKEN
export TF_STATE_NAME=default

terraform init \
    -backend-config="address=https://gitlab.com/api/v4/projects/YOUR-PROJECT-ID/terraform/state/TF_STATE_NAME" \
    -backend-config="lock_address=https://gitlab.com/api/v4/projects/YOUR-PROJECT-ID/terraform/state/TF_STATE_NAME/lock" \
    -backend-config="unlock_address=https://gitlab.com/api/v4/projects/YOUR-PROJECT-ID/terraform/state/TF_STATE_NAME/lock" \
    -backend-config="username=visuals3d" \
    -backend-config="password=GITLAB_ACCESS_TOKEN" \
    -backend-config="lock_method=POST" \
    -backend-config="unlock_method=DELETE" \
    -backend-config="retry_wait_min=5"

terraform plan -var-file="local.tfvars" -out tfplan
terraform apply tfplan

terraform output talosconfig >> talosconfig
terraform output talosconfig >> kubeconfig

export KUBECONFIG=./kubeconfig
kubectl get nodes

Setup secrets

Now that the Rocket Pad Platform is bootstrapped and you have access via kubectl you will see only Argocd pods and some kube-system pods. Everything else can only be bootstrapped if Argocd has access to pull our Rocket Pad Platform repositories as well as your repositories. In order to grant this access create a private git repo credentials template for argocd and apply it as a secret to your cluster.

Create the secret.yaml file

secret.yaml
password: ACCESS_TOKEN
username: USERNAME

If the url is not directly referring to a single repository but to a group or project folder in git the access rights will propagate and be used for all repositories within that Group, which is recommended for convenience.

Access Argo CD UI

Now your RPP Cluster will bootstrap completely. To check the state and debug any issues you can start a port forward the Argo CD UI and see how your Rocket Pad Platform is build bit by bit.

kubectl port-forward svc/argocd-server -n argocd 8080:8080
kubectl get secrets/argocd-initial-admin-secret -n argocd --template={{.data.password}}  | base64 -d

Now open localhost:8080 and login with username admin and the init admin password exported above.

Supported Rollout targets​

Prerequisites​

Tools​

Kubernetes Cluster Requirements​

Cluster​

Nodes​

Preparing a Platform Git Repository​

2. Load Rocket Pad Platform code​

3. Bootstrap folder​

6. (Optional no IaC Module) Bootstrap on already existing Kubernetes Cluster​

7. (Optional IaC Module) Terraform IaC based bootstrap​

Add sensitive config​

Example with Gitlab for Terraform state​

Setup secrets​

Access Argo CD UI​