Skip to content

Latest commit

 

History

History
123 lines (85 loc) · 5.25 KB

BOOTSTRAP.md

File metadata and controls

123 lines (85 loc) · 5.25 KB
Raw

How to bootstrap a Catena-X environment

The following guide will walk you through the process of creating a new Catena-X environment from scratch. After completing these steps the following resources will be created:

  • an AKS cluster
  • ArgoCD that is accessible via configured domain
  • a default stack of applications to support your DevOps activities

Create an AKS cluster

To set up AKS, we are using terraform.

NOTE: Applying terraform plans is done locally, since we do not expect a lot of clusters. Also, we'll use Gardener in foreseeable future and the whole setup will change.

Create a service principal

NOTE: This Step is optional. You can also reuse existing ones

To set up the AKS cluster, we need an Azure Service Principal Account. You can create it like follows:

# Follow login instructions in your browser
az login --tenant catenax.onmicrosoft.com
az ad sp create-for-rbac --skip-assignment

The last command will print a json object with the service principal details. The two important properties are appId and password, which will be used as credentials for the AKS cluster.

Create the necessary Azure resources

terraform init

# Set the service principle to use via environment
# <sp client id> is the value of 'appId' from the service principal json output
# <sp client secret> is the value of 'password' from the service principal json output
export TF_VAR_service_principal_client_id=<sp client id>
export TF_VAR_service_principal_client_secret=<sp client secret>

terraform plan -var-file=environments/<environment>.tfvars -out <environment>.plan
terraform apply <environment>.plan

Install Core ArgoCD Cluster

To install the initial ArgoCD instance you have to connect kubectl to the previously created AKS instance. Therefor open the AKS resource in Azure portal and follow the connect instructions.

Once you are connected via kubectl, you can use kustomize to apply the necessary kubernetes resources. From the top level directory of this repository run:

kubect apply -k argocd

Note: You may have to execute this twice, since we are using ArgoCD CRDs, which are not recognized on the first run.

Configure GitHub OAuth app for login

We enable users of ArgoCD to log in with their GitHub account. To get that working, we need to create an OAuth App inside our GitHub organization and configure ArgoCD to use it. We need an OAuth app for each of our ArgoCD instances, since each instance will have a unique redirect URL.

You can follow the official guide from GitHub on how to create an OAuth app.

You'll need to fill in the following information:

Entering the necessary information and clicking the button Register Application will create the OAuth app and generate a clientID. Next step is to create a clientSecret, by clicking Generate a new client secret in the Client secrets section. Remember both, clientID and clientSecret, since they are needed for ArgoCD configuration. Also, the clientSecret will disappear once you refresh the page. If you accidentally refreshed the page, without remembering the secret, just delete it and create a new one.

Configuring ArgoCD to use the OAuth app is yet still a manual process. After installing ArgoCD like described in the previous section, you'll find a configMap resource called 'argocd-cm' in the argocd namespace of the kubernetes cluster. This configMap contains the Dex settings for GitHub login.

You can edit the configMap in place, by connecting to the kubernetes cluster hosting the ArgoCD instance you want to configure. Once you are connected via kubectl, you can interactively edit the configMap with this command: kubectl -n argocd edit configmap argocd-cm. This will open the default editor configured for your shell. You should see a YAML definition similar to this:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
data:
  dex.config: |
    connectors:
      - type: github
        id: github
        name: GitHub
        config:
          clientID: $dex.github.clientId
          clientSecret: $dex.github.clientSecret
          orgs:
          - name: catenax-ng
  url: https://argo.core.demo.catena-x.net

Replace the placeholders $dex.github.clientId and $dex.github.clientSecretwith the values from your newly created GitHub OAuth app and save the changes. Afterwards verify, if you can log in to ArgoCD via GitHub.

Environment provisioning via Core ArgoCD

To deploy applications via the Core ArgoCD to remote clusters, you need to introduce the remote cluster to the Core ArgoCD instance. Afterwards, you can configure the cluster as destination in the needed ArgoCD ApplicationSets.

Introducing a new remote cluster

Adding remote clusters to an ApplicationSet