Copilot skills for building CLI, container images, and installing Radius

.github/copilot-instructions.md

@@ -40,6 +40,9 @@ The following instruction files are available:
 These skills are available for specific Radius tasks under the `.github/skills/` directory.
 
 - **[Architecture Documentation](skills/architecture-documenter/SKILL.md)** - Document and diagram application architecture
+- **[Build Radius CLI](skills/radius-build-cli/SKILL.md)** - Build the `rad` CLI binary from source
+- **[Build and Push Container Images](skills/radius-build-images/SKILL.md)** - Build and push Radius Docker images to a registry
+- **[Install Radius from Custom Images](skills/radius-install-custom/SKILL.md)** - Install Radius on Kubernetes from custom-built images
 - **[Contributing Docs Updater](skills/contributing-docs-updater/SKILL.md)** - Update, create, review, and find gaps in contributor documentation
 
 ## How to Use

.github/skills/radius-build-cli/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: radius-build-cli
+description: 'Build the Radius CLI (rad) binary from source. Use when compiling rad, cross-compiling for another platform, creating a debug build, or verifying the CLI builds correctly after code changes.'
+argument-hint: 'Optional: build variant (e.g. debug, linux-amd64) — or leave blank for default release build'
+---
+
+# Build Radius CLI
+
+Build the `rad` CLI binary from source using the project's Makefile build system.
+
+## Overview
+
+The Radius CLI (`rad`) is a Go binary located at `cmd/rad/main.go`. The build system uses GNU Make with
+build configuration split across files in the `build/` directory. The primary build targets are defined
+in `build/build.mk` and version information is injected via linker flags defined in `build/version.mk`.
+
+## Build Outputs
+
+Binaries are written to `./dist/<GOOS>_<GOARCH>/<buildtype>/rad` where:
+- `<GOOS>` is the target operating system (e.g., `darwin`, `linux`, `windows`)
+- `<GOARCH>` is the target architecture (e.g., `amd64`, `arm64`)
+- `<buildtype>` is `release` (default) or `debug` (when `DEBUG=1`)
+
+## Procedure
+
+### Step 1: Verify Prerequisites
+
+Confirm the following tools are available before building:
+
+1. **Go**: Run `go version` to verify Go is installed. The required version is specified in `go.mod`.
+2. **Make**: Run `make --version` to verify GNU Make is available.
+3. **Git**: Run `git rev-parse --is-inside-work-tree` to confirm we are in a Git repository (needed for version injection).
+
+If any prerequisite is missing, stop and report clearly which tool needs to be installed.
+
+### Step 2: Detect Target Platform
+
+Determine the build target platform:
+
+- Run `go env GOOS` to detect the current OS.
+- Run `go env GOARCH` to detect the current architecture.
+
+Report the detected platform to the user (e.g., `darwin/arm64`).
+
+### Step 3: Build the CLI
+
+Build the `rad` binary using the Makefile:
+
+```bash
+make build-rad
+```
+
+This compiles only the `rad` CLI binary for the current OS and architecture. Version metadata
+(commit SHA, Git version, release channel, chart version) is injected automatically via `-ldflags`.
+
+**Build variants:**
+
+| Command | Description |
+|---|---|
+| `make build-rad` | Build `rad` for the current platform (release mode) |
+| `DEBUG=1 make build-rad` | Build `rad` with debug symbols (`-gcflags "all=-N -l"`) |
+| `make build-rad-<os>-<arch>` | Cross-compile for a specific platform (e.g., `make build-rad-linux-amd64`) |
+| `make build` | Build all binaries, packages, and Bicep tooling |
+
+Use `make build-rad` unless the user explicitly requests a different target, debug build, or cross-compilation.
+
+### Step 4: Verify the Build
+
+After the build completes successfully:
+
+1. Confirm the binary exists at the expected output path:
+   ```bash
+   ls -lh ./dist/$(go env GOOS)_$(go env GOARCH)/release/rad
+   ```
+   If `DEBUG=1` was used, check `./dist/$(go env GOOS)_$(go env GOARCH)/debug/rad` instead.
+
+2. Run the built binary to verify it executes:
+   ```bash
+   ./dist/$(go env GOOS)_$(go env GOARCH)/release/rad version
+   ```
+
+3. Report the build results:
+   - Binary path and size
+   - Version information from `rad version` output
+   - Build mode (release or debug)
+
+### Step 5: Report Result
+
+Summarize the build:
+
+```
+Build complete!
+Binary: ./dist/<os>_<arch>/<buildtype>/rad
+Version: <version output>
+```
+
+## Quick Reference
+
+| Goal | Command |
+|------|---------|
+| Build rad (current platform) | `make build-rad` |
+| Debug build | `DEBUG=1 make build-rad` |
+| Cross-compile | `make build-rad-<os>-<arch>` |
+| Build everything | `make build` |

.github/skills/radius-build-images/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: radius-build-images
+description: 'Build Radius container images from source for local development and testing. Push to any container registry that your Kubernetes cluster can pull from.'
+argument-hint: 'Optional: target registry (e.g. ghcr.io/my-username, myacr.azurecr.io/radius) — or leave blank to be prompted'
+---
+
+# Radius: Build and Push Container Images
+
+Build Radius service images from source and push them to a container registry that your Kubernetes cluster can reach. This follows the workflow documented in `docs/contributing/contributing-code/contributing-code-building/README.md` and `docs/contributing/contributing-code/contributing-code-control-plane/generating-and-installing-custom-build.md`.
+
+## Images
+
+The following images are built from this repository:
+
+| Image | Source |
+|-------|--------|
+| `ucpd` | `deploy/images/ucpd` |
+| `applications-rp` | `deploy/images/applications-rp` |
+| `dynamic-rp` | `deploy/images/dynamic-rp` |
+| `controller` | `deploy/images/controller` |
+| `bicep` | `deploy/images/bicep` |
+| `pre-upgrade` | `deploy/images/pre-upgrade` |
+| `testrp` | `test/testrp` |
+| `magpiego` | `test/magpiego` |
+
+> **Not built here:** The `deployment-engine` and `dashboard` images are **not** built from this repository. They are published separately to `ghcr.io/radius-project/`. When installing with a custom registry you need to pin these to their public location — see the `radius-install-custom` skill.
+
+## Procedure
+
+### Step 1: Verify Prerequisites
+
+Check that the required tools are available:
+
+1. **Docker**: Run `docker info` — confirm the Docker daemon is running.
+2. **Make**: Run `make --version` — confirm GNU Make is installed.
+3. **Go**: Run `go version` — the required version is in `go.mod`.
+
+If any prerequisite is missing, stop and report which tool needs to be installed.
+
+### Step 2: Set the Registry
+
+Ask the user for their container registry if `DOCKER_REGISTRY` is not already set. The registry must be one the user can push to and their Kubernetes cluster can pull from.
+
+```sh
+export DOCKER_REGISTRY=ghcr.io/<your-registry>
+export DOCKER_TAG_VERSION=latest
+```
+
+> **Note:** The user must already be logged in to the registry (`docker login`, `az acr login`, etc.). If you get authentication errors, ask the user to log in first.
+
+> **Default:** If `DOCKER_REGISTRY` is not set, the Makefile defaults to your OS username (from `build/docker.mk`). Always set it explicitly.
+
+### Step 3: Build and Push the Images
+
+Build all images and push them to the registry in one command:
+
+```sh
+DOCKER_REGISTRY=${DOCKER_REGISTRY} DOCKER_TAG_VERSION=${DOCKER_TAG_VERSION} make docker-build docker-push
+```
+
+This compiles all Go binaries, builds each Docker image, and pushes them to the registry. The `copy-manifests` step runs automatically.
+
+To build and push a **single image** (useful for fast iteration):
+
+```sh
+make docker-build-<image-name> && make docker-push-<image-name>
+# e.g. make docker-build-applications-rp && make docker-push-applications-rp
+```
+
+### Step 4: Verify
+
+Confirm the images were pushed:
+
+```sh
+docker images --filter "reference=${DOCKER_REGISTRY}/*:${DOCKER_TAG_VERSION}"
+```
+
+Then proceed to the `radius-install-custom` skill to install Radius on your cluster.
+
+## Private Registries
+
+For private registries that require authentication to pull, you will need to create a Kubernetes image pull secret when installing. See the `radius-install-custom` skill for details.
+
+## Multi-Architecture Builds
+
+For native `linux/arm64` images (e.g. on Apple Silicon with an arm64 Kubernetes cluster), first set up buildx (one-time):
+
+```sh
+make configure-buildx
+```
+
+Then build and push all architectures:
+
+```sh
+DOCKER_REGISTRY=${DOCKER_REGISTRY} DOCKER_TAG_VERSION=${DOCKER_TAG_VERSION} make docker-multi-arch-push
+```
+
+## Quick Reference
+
+| Goal | Command |
+|------|---------|
+| Set registry | `export DOCKER_REGISTRY=ghcr.io/<your-registry> && export DOCKER_TAG_VERSION=latest` |
+| Build + push all images | `make docker-build docker-push` |
+| Build all images | `make docker-build` |
+| Push all images | `make docker-push` |
+| Single image build + push | `make docker-build-<name> && make docker-push-<name>` |
+| Multi-arch build + push | `make docker-multi-arch-push` |
+| Setup buildx (one-time) | `make configure-buildx` |
+
+## Key Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DOCKER_REGISTRY` | OS username (from `build/docker.mk`) | Target registry for built images. Set explicitly to your registry. |
+| `DOCKER_TAG_VERSION` | `latest` | Image tag |
+| `DOCKER_CACHE_GHA` | `0` | Set to `1` to enable GitHub Actions layer caching |

.github/skills/radius-install-custom/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: radius-install-custom
+description: 'Install Radius on a Kubernetes cluster from custom-built container images. Works with any cluster and any registry the cluster can pull from.'
+argument-hint: 'Optional: registry and tag (e.g. ghcr.io/my-username latest) — or leave blank to be prompted'
+---
+
+# Install Radius from Custom Images
+
+Install the Radius control plane on a Kubernetes cluster using images you built from source. This follows the workflow documented in `docs/contributing/contributing-code/contributing-code-control-plane/generating-and-installing-custom-build.md`.
+
+## Prerequisites
+
+- Images built and pushed using the `radius-build-images` skill
+- `kubectl` configured for the target cluster (`kubectl cluster-info`)
+- `rad` CLI available in `$PATH` (see the `radius-build-cli` skill, or use a released version)
+
+## Procedure
+
+### Step 1: Verify Prerequisites
+
+Run these checks:
+
+1. **rad CLI**: `rad version` — confirm the rad CLI is installed and working.
+2. **kubectl context**: `kubectl config current-context` — confirm the current kubeconfig context points to the target cluster.
+3. **kubectl connectivity**: `kubectl cluster-info` — confirm the cluster is reachable.
+
+If `rad` is not in `$PATH` but was built locally, the binary is at `./dist/$(go env GOOS)_$(go env GOARCH)/release/rad`.
+
+### Step 2: Confirm Registry and Tag
+
+Confirm the registry and tag match what was used in the build step:
+
+```sh
+echo "Registry: ${DOCKER_REGISTRY:-<not set>}"
+echo "Tag: ${DOCKER_TAG_VERSION:-latest}"
+```
+
+If not set, ask the user for the registry they pushed images to during the `radius-build-images` skill. Set the variables:
+
+```sh
+export DOCKER_REGISTRY=ghcr.io/<your-registry>
+export DOCKER_TAG_VERSION=latest
+```
+
+### Step 3: Check for Existing Installation
+
+```sh
+rad version
+```
+
+Look at the control plane status in the output:
+
+- **Not installed** → proceed to Step 4 (fresh install).
+- **Already installed** → add `--reinstall` to the install command in Step 4.
+
+### Step 4: Install Radius
+
+Install from the local Helm chart, pointing to your custom image registry:
+
+```sh
+rad install kubernetes \
+  --chart deploy/Chart/ \
+  --set global.imageRegistry=${DOCKER_REGISTRY} \
+  --set global.imageTag=${DOCKER_TAG_VERSION} \
+  --set de.image=ghcr.io/radius-project/deployment-engine \
+  --set de.tag=latest \
+  --set dashboard.image=ghcr.io/radius-project/dashboard \
+  --set dashboard.tag=latest
+```
+
+For a **reinstall** over an existing installation, add `--reinstall`:
+
+```sh
+rad install kubernetes \
+  --chart deploy/Chart/ \
+  --set global.imageRegistry=${DOCKER_REGISTRY} \
+  --set global.imageTag=${DOCKER_TAG_VERSION} \
+  --set de.image=ghcr.io/radius-project/deployment-engine \
+  --set de.tag=latest \
+  --set dashboard.image=ghcr.io/radius-project/dashboard \
+  --set dashboard.tag=latest \
+  --reinstall
+```
+
+For **private registries** that require authentication to pull, first create a Kubernetes secret:
+
+```sh
+kubectl create namespace radius-system 2>/dev/null || true
+kubectl create secret docker-registry regcred \
+  --docker-server=${DOCKER_REGISTRY} \
+  --docker-username=<username> \
+  --docker-password=<password> \
+  -n radius-system
+
+rad install kubernetes \
+  --chart deploy/Chart/ \
+  --set global.imageRegistry=${DOCKER_REGISTRY} \
+  --set global.imageTag=${DOCKER_TAG_VERSION} \
+  --set de.image=ghcr.io/radius-project/deployment-engine \
+  --set de.tag=latest \
+  --set dashboard.image=ghcr.io/radius-project/dashboard \
+  --set dashboard.tag=latest \
+  --set-string 'global.imagePullSecrets[0].name=regcred'
+```
+
+To target a different cluster without changing the active kubeconfig context, add `--kubecontext <context-name>`.
+
+> **Why pin `de.image`/`de.tag` and `dashboard.image`/`dashboard.tag`?** The `deployment-engine` and `dashboard` images are not built in this repository — they come from `ghcr.io/radius-project/`. Setting `global.imageRegistry` would otherwise redirect those pulls to your registry where they don't exist.
+
+### Step 5: Verify the Installation
+
+1. Check that all pods are running:
+
+   ```sh
+   kubectl get pods -n radius-system
+   ```
+
+   Wait for all pods to reach `Running` and `1/1` ready status.
+
+2. Verify the control plane version:
+
+   ```sh
+   rad version
+   ```
+
+3. Confirm images are from the correct registry:
+
+   ```sh
+   kubectl get pods -n radius-system -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{range .spec.containers[*]}{.image}{"\n"}{end}{end}'
+   ```
+
+### Step 6: Initialize the Environment (Optional)
+
+If this is a fresh cluster, set up a Radius workspace and environment:
+
+```sh
+rad init
+```
+
+## Quick Reference
+
+| Goal | Command |
+|------|---------|
+| Set registry | `export DOCKER_REGISTRY=ghcr.io/<your-registry> && export DOCKER_TAG_VERSION=latest` |
+| Fresh install | `rad install kubernetes --chart deploy/Chart/ --set global.imageRegistry=${DOCKER_REGISTRY} --set global.imageTag=${DOCKER_TAG_VERSION} --set de.image=ghcr.io/radius-project/deployment-engine --set de.tag=latest --set dashboard.image=ghcr.io/radius-project/dashboard --set dashboard.tag=latest` |
+| Reinstall | Add `--reinstall` to the above |
+| Check status | `rad version` |
+| Check pods | `kubectl get pods -n radius-system` |
+| Uninstall | `rad uninstall kubernetes --yes` |
+| Initialize environment | `rad init` |
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `ImagePullBackOff` on deployment-engine or dashboard | `global.imageRegistry` redirected external images to your registry | Ensure `--set de.image=ghcr.io/radius-project/deployment-engine --set de.tag=latest --set dashboard.image=ghcr.io/radius-project/dashboard --set dashboard.tag=latest` are set |
+| `ImagePullBackOff` on Radius images | Cluster cannot pull from the registry | Verify images were pushed (`docker images`), the cluster can reach the registry, and authentication is configured if needed |
+| `rad install` fails with "another operation in progress" | Helm release stuck in `pending-upgrade` or `pending-install` | `helm rollback radius <last-good-revision> -n radius-system`, then retry |
+| Pods crash with `exec format error` | Image architecture doesn't match node architecture | Rebuild with `make docker-multi-arch-push` (see the `radius-build-images` skill) |