Skip to content

getting-started.md

Latest commit

 

History

History
244 lines (162 loc) · 9.82 KB

getting-started.md

File metadata and controls

244 lines (162 loc) · 9.82 KB
Raw

Skupper VMS Hello World

This tutorial will walk you through running the vms management server, setting up a management backbone on a Kubernetes cluster, and connecting a van to the backbone from a second Kubernetes cluster.

Prerequisites:

  • Access to at least two Kubernetes clusters, from any provider you choose.

    NOTE: The cluster running the management backbone must be an OpenShift cluster as the Management Controller requires routes

  • The kubectl command-line tool, version 1.15 or later (installation guide).

  • cert-manager installed on the cluster you are running the management server from

    kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.2/cert-manager.yaml

    You can get the most recent version from https://cert-manager.io/docs/installation/kubectl/

    NOTE: cert-manager is included in OpenShift

  • Keycloak instance running and configured for the management-controller. For instructions, see Keycloak setup guide.

  • Helmfile: To deploy cert-manager, PostgreSQL, and the management-server chart from this repository, use the Helmfile under charts/helmfile/. Start at charts/README.md (full deployment details in charts/helmfile/README.md). The sections below describe a manual YAML-based flow for this tutorial.

Part 1: Set up the management server

Step 1: Access your Kubernetes cluster

Open a new terminal window and run the following commands:

export KUBECONFIG=~/.kube/management-server
<provider-specific login command>

Note: The login procedure varies by provider

Step 2: Create your Kubernetes namespace for the management server to run in

Note: This must be done on an OpenShift cluster as the Management Controller requires routes

kubectl create namespace vms
kubectl config set-context --current --namespace vms

Step 3: Set up PostgreSQL and supporting cluster components

The repository no longer includes a top-level yaml/ directory of sample manifests. Deploy cert-manager, Bitnami PostgreSQL (with schema from charts/helmfile/resources/db-setup.sql applied via Helmfile’s init hook), and optionally the management-server chart using charts/helmfile:

cd charts/helmfile
# Edit values/common.yaml for namespaces, storage, and release toggles as needed.
helmfile sync

Create postgres-credentials and keycloak-config Secrets as described in charts/helmfile/README.md. Align your kubectl context and namespace with releases.postgresql.namespace and your management-server namespace.

Step 4: Install Node packages

From the root of the repo, run the following command to install the necessary Node packages. Then, navigate to the management-controller directory.

pnpm install
cd ./components/management-controller

Note: It is required to use pnpm, not npm, as the package manager for the install.

Step 5: Configure environment variables

Copy the example env file in /components/management-controller and edit it for your cluster.

cd components/management-controller && cp .env.example .env

Set at least PGDATABASE, APP_USER_PASSWORD, APP_SYSTEM_PASSWORD, SKX_STANDALONE_NAMESPACE, VMS_SESSION_SECRET (see .env.example for variables).

To set PGHOST to the cluster IP of the postgres service (if you are not using OpenShift), run:

# Append or merge into .env, e.g.:
echo "PGHOST=$(kubectl -n vms get svc postgres -o json | jq -r .spec.clusterIP)" >> /path/to/.env

Alternatively, you can keep exporting variables in your shell; those override values from .env.

Step 6: Set up the database schema

If you deployed PostgreSQL with Helmfile, the Bitnami chart applies charts/helmfile/resources/db-setup.sql on first init—you can skip this step unless you are repairing a database or using a custom Postgres install.

To apply the schema manually, run the following from the repository root, piping charts/helmfile/resources/db-setup.sql into psql on the Postgres workload. Set $PGUSER and $PGDATABASE to match your deployment (or use literals).

export PGUSER=access
export PGDATABASE=studiodb

On OpenShift

kubectl -n vms exec -it statefulsets/postgres -- psql -U $PGUSER -d $PGDATABASE -v APP_USER_PASSWORD=password -v APP_SYSTEM_PASSWORD=password < charts/helmfile/resources/db-setup.sql

On Kubernetes

kubectl exec -it deployment/postgres -- psql -U $PGUSER -d $PGDATABASE -v APP_USER_PASSWORD=password -v APP_SYSTEM_PASSWORD=password < charts/helmfile/resources/db-setup.sql

To tear down application objects in the database for maintenance, the optional script charts/helmfile/resources/drop.sql is available (not run by Helmfile).

NOTE: If using minikube, run minikube tunnel in a separate terminal.

Step 7: Start the server (for local development)

Place keycloak.json in components/management-controller/ as described in the Keycloak setup guide; the API server expects it at startup.

From inside the management-controller directory, run:

Note: If you are on OpenShift, you can port-forward localhost port 5432 to your pod/postgres-0 and set PGHOST=localhost.

# under components/management-controller, run:
node index.js

Part 2: Setting up the backbone on a Kubernetes cluster

Step 1: Access your Kubernetes cluster

Open a new terminal window and run the following commands:

export KUBECONFIG=~/.kube/backbone
<provider-specific login command>

Step 2: Create a namespace for your backbone to run on

kubectl create namespace <backbone-namespace>
kubectl config set-context --current --namespace <backbone-namespace>

Step 3: Create a backbone network and site in the vms console

  1. Navigate to http://localhost:8085 and open the "backbones" tab
  2. Create a new backbone and give it a name
  3. Click on the newly created backbone and click the "Activate" button
  4. Click "Create site...", give it a name, and select "skx-prototype" as the target platform
  5. Create an access point on the newly created site with kind: "manage"
  6. Create a second access point with kind: "van"
  7. Click the "Bootstrap Step 1" download link and apply the downloaded yaml in your backbone namespace
  8. Run kubectl exec -it <vms-site-pod> -c controller -- skxhosts
  9. Copy the output ingress data into the "Upload ingress data" section in the vms console under "Bootstrap Step 2"
  10. Once the host and port data appear on the "manage" access point, click the "Bootstrap Step 3" download link and apply the downloaded yaml file in your backbone namespace

Part 3: Connecting a van to the management backbone

Step 1: Access your Kubernetes cluster

Open a new terminal window and run the following commands:

export KUBECONFIG=~/.kube/van
<provider-specific login command>

Note: The login procedure varies by provider

Step 2: Set up the skupper-controller with multi-van crds and images

  1. Apply the following crds to your cluster:

    kubectl apply -f https://github.com/fgiorgetti/skupper/raw/refs/heads/multi-van/config/crd/bases/skupper_network_crd.yaml
kubectl apply -f https://github.com/fgiorgetti/skupper/raw/refs/heads/multi-van/config/crd/bases/skupper_network_link_crd.yaml
kubectl apply -f https://github.com/fgiorgetti/skupper/raw/refs/heads/multi-van/config/crd/bases/skupper_inter_network_ingress_crd.yaml
kubectl apply -f https://github.com/fgiorgetti/skupper/raw/refs/heads/multi-van/config/crd/bases/skupper_network_access_crd.yaml
kubectl apply -f https://github.com/fgiorgetti/skupper/raw/refs/heads/multi-van/config/crd/bases/skupper_certificate_request_crd.yaml

  2. Change the skupper-controller deployment to use multi-van images

    a. Run kubectl edit deployment skupper-controller -n skupper b. Swap the kube-adaptor, skupper-router, and controller images for the following:

    • quay.io/fgiorgetti/kube-adaptor:multi-van
    • quay.io/tedlross/skupper-router:multi-van
    • quay.io/fgiorgetti/controller:multi-van

  3. Run kubectl edit clusterrole skupper-controller -n skupper and add the following to the skupper.io apiGroups section

    • networks
    • networks/status
    • internetworkingresses
    • internetworkingresses/status
    • networklinks
    • networklinks/status
    • networkaccesses
    • networkaccesses/status
    • certificaterequests
    • certificaterequests/status

Step 3: Create your Kubernetes namespace for the van to run in

kubectl create namespace van
kubectl config set-context --current --namespace van

Step 4: Create a skupper site in the van namespace

skupper site create van-site

Step 5: Create the van in the vms console

  1. In the console, navigate to the "VANs" tab and click "Create Externally-Created VAN..."
  2. Give it a name and click "Submit"
  3. Click on the newly created van and navigate to the "Configuration" tab
  4. Select the configuration type of "VAN Site Connected to the Management Backbone" and select the backbone we created in the previous steps from the dropdown
  5. Click the "download configuration" button and apply the downloaded yaml in the van namespace

Part 4: Confirm everything is set up properly

In order to check that the van and backbone are connected and communicating, run the following command in the backbone terminal:

kubectl get routes

There should be two active routes, one for the "manage" access point and another for the "van" access point