Add clusterctl/stackit CLI to devcontainer, persist dev state, update quick-start docs

- .devcontainer/devcontainer.json: add named volumes for bash history
  (/commandhistory) and docker-in-docker state (/var/lib/docker) so both
  survive container rebuilds; set HISTFILE accordingly
- .devcontainer/post-install.sh: install clusterctl and the stackit CLI
  (with bash completions), flush bash history after every command via
  PROMPT_COMMAND, verify both tools at the end of setup
- .gitignore: ignore local dev/debug artifacts (.DS_Store, cluster.yaml,
  kind-config.yaml, devcontainer-lock.json)
- docs/src/quick-start.md: document the .stackit/ service-account key
  convention, add the STACKIT_SSH_KEY_NAME env var (used by the bastion
  cluster template), add an optional kind-config.yaml section for
  enterprise TLS-intercepting proxies (e.g. Zscaler), and write the
  generated cluster manifest to a file before applying it

Author: Herbaert

.devcontainer/devcontainer.json

@@ -13,6 +13,10 @@
   },
 
   "runArgs": ["--privileged", "--init"],
+  "mounts": [
+    "source=${localWorkspaceFolderBasename}-bashhistory,target=/commandhistory,type=volume",
+    "source=${localWorkspaceFolderBasename}-docker,target=/var/lib/docker,type=volume"
+  ],
 
   "customizations": {
     "vscode": {
@@ -27,7 +31,8 @@
   },
 
   "remoteEnv": {
-    "GO111MODULE": "on"
+    "GO111MODULE": "on",
+    "HISTFILE": "/commandhistory/.bash_history"
   },
 
   "onCreateCommand": "bash .devcontainer/post-install.sh"

.devcontainer/post-install.sh

@@ -42,6 +42,15 @@ if ! grep -q "source /usr/share/bash-completion/bash_completion" ~/.bashrc 2>/de
   echo "Added bash-completion to .bashrc"
 fi
 
+# Persist bash history on the /commandhistory volume (HISTFILE is set via
+# devcontainer.json remoteEnv) and flush it after every command instead of
+# only on a clean shell exit.
+mkdir -p /commandhistory
+if ! grep -q "PROMPT_COMMAND='history -a'" ~/.bashrc 2>/dev/null; then
+  echo "PROMPT_COMMAND='history -a'" >> ~/.bashrc
+  echo "Added persistent bash history to .bashrc"
+fi
+
 echo ""
 echo "------------------------------------"
 echo "Installing development tools..."
@@ -99,6 +108,44 @@ if command -v kubectl &> /dev/null; then
   fi
 fi
 
+# Install clusterctl
+if ! command -v clusterctl &> /dev/null; then
+  echo "Installing clusterctl..."
+  curl -Lo /usr/local/bin/clusterctl "https://github.com/kubernetes-sigs/cluster-api/releases/latest/download/clusterctl-linux-${ARCH}"
+  chmod +x /usr/local/bin/clusterctl
+  echo "clusterctl installed successfully"
+fi
+
+# Generate clusterctl bash completion
+if command -v clusterctl &> /dev/null; then
+  if clusterctl completion bash > "${BASH_COMPLETIONS_DIR}/clusterctl" 2>/dev/null; then
+    echo "clusterctl completion installed"
+  else
+    echo "WARNING: Failed to generate clusterctl completion"
+  fi
+fi
+
+# Install stackit CLI
+if ! command -v stackit &> /dev/null; then
+  echo "Installing stackit CLI..."
+  STACKIT_CLI_VERSION=$(curl -Ls https://api.github.com/repos/stackitcloud/stackit-cli/releases/latest | grep '"tag_name"' | cut -d '"' -f4 | sed 's/^v//')
+  curl -Lo /tmp/stackit-cli.tar.gz "https://github.com/stackitcloud/stackit-cli/releases/download/v${STACKIT_CLI_VERSION}/stackit-cli_${STACKIT_CLI_VERSION}_linux_${ARCH}.tar.gz"
+  tar -xzf /tmp/stackit-cli.tar.gz -C /tmp stackit
+  mv /tmp/stackit /usr/local/bin/stackit
+  chmod +x /usr/local/bin/stackit
+  rm -f /tmp/stackit-cli.tar.gz
+  echo "stackit CLI installed successfully"
+fi
+
+# Generate stackit CLI bash completion
+if command -v stackit &> /dev/null; then
+  if stackit completion bash > "${BASH_COMPLETIONS_DIR}/stackit" 2>/dev/null; then
+    echo "stackit completion installed"
+  else
+    echo "WARNING: Failed to generate stackit completion"
+  fi
+fi
+
 # Generate Docker bash completion
 if command -v docker &> /dev/null; then
   if docker completion bash > "${BASH_COMPLETIONS_DIR}/docker" 2>/dev/null; then
@@ -142,6 +189,8 @@ echo "------------------------------------"
 kind version
 kubebuilder version
 kubectl version --client
+clusterctl version
+stackit --version
 docker --version
 go version
 

.gitignore

@@ -2,6 +2,13 @@
 .env
 .stackit
 
+# Local dev/debug artifacts
+.DS_Store
+/cluster*.yaml
+/kind-config.yaml
+.devcontainer/devcontainer-lock.json
+.ssh/
+
 # Binaries for programs and plugins
 *.exe
 *.exe~

docs/src/quick-start.md

@@ -8,23 +8,53 @@ image, and machine type.
 
 Furthermore, make sure that the provided service-account has [an appropriate set of permissions](./topics/iam-permissions.md).
 
+Place the downloaded service-account JSON key at `.stackit/cluster-api-provider-stackit.json`
+inside the repo (create the `.stackit/` directory if it does not exist yet). It is listed in
+`.gitignore`, so the key is never committed, and the path works identically for every
+contributor regardless of where the repo is checked out.
+
 ```sh
 export STACKIT_PROJECT_ID=<project-uuid>
 export STACKIT_REGION=eu01
 export STACKIT_NETWORK_ID=<network-uuid>
 export STACKIT_IMAGE_ID=<image-uuid>
-export STACKIT_MACHINE_TYPE=c2i.2
+export STACKIT_MACHINE_TYPE=c2i.4
+export STACKIT_SSH_KEY_NAME=""
 export STACKIT_SERVICE_ACCOUNT_JSON_FILE=./.stackit/cluster-api-provider-stackit.json
 export STACKIT_SERVICE_ACCOUNT_JSON_B64="$(base64 < "${STACKIT_SERVICE_ACCOUNT_JSON_FILE}" | tr -d '\n')"
 export STACKIT_CLOUD_CONTROLLER_MANAGER_IMAGE=ghcr.io/stackitcloud/cloud-provider-stackit/cloud-controller-manager:v1.35.3
 ```
 
-The default template does not configure SSH access. To use an SSH key, add
-`sshKeyName: <key-name>` to the `StackitMachineTemplate` specs before creating
-the workload cluster.
+The default template (`templates/cluster-template.yaml`) does not configure SSH access. To use
+an SSH key, add `sshKeyName: <key-name>` to the `StackitMachineTemplate` specs before creating
+the workload cluster. If you use the bastion variant instead
+(`templates/cluster-template-bastion.yaml`), set `STACKIT_SSH_KEY_NAME` above to your key name,
+it is substituted into that template directly.
 
 ## Create the management cluster
 
+### Optional: `kind-config.yaml` for enterprise proxies (e.g. Zscaler)
+
+If your machine sits behind a TLS-intercepting enterprise proxy such as Zscaler, outbound HTTPS
+calls made from inside the `kind` node container (pulling images, talking to the STACKIT API,
+etc.) will fail certificate validation. The node runs as its own container with its own OS
+certificate store, which does not include the proxy's root CA even though your host already
+trusts it. Mount the host's CA bundle into the node at the same path it expects:
+
+```yaml
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+nodes:
+- role: control-plane
+  extraMounts:
+  - hostPath: /etc/ssl/certs/ca-certificates.crt
+    containerPath: /etc/ssl/certs/ca-certificates.crt
+    readOnly: true
+```
+
+Save this as `kind-config.yaml` in the repo root before running `kind create cluster` below. If
+you are not behind such a proxy, drop the `--config kind-config.yaml` flag from the command.
+
 ```sh
 kind create cluster --name capi-stackit
 kubectl config use-context kind-capi-stackit
@@ -68,7 +98,8 @@ clusterctl init \
  clusterctl generate cluster "${CLUSTER_NAME}" \
    --from templates/cluster-template.yaml \
    --target-namespace "${NAMESPACE}" \
-   | kubectl apply -f -
+   > cluster.yaml
+ kubectl apply -f cluster.yaml
  ```
 
  Watch progress: