Add app-deploy workflow to the azure-kubernetes skill - #2696
Add app-deploy workflow to the azure-kubernetes skill#2696Tom Gamble (gambtho) merged 20 commits into
Conversation
Carry over the deploy workflow, references, knowledge packs, and templates from the closed PR microsoft#1827 fork branch into a nested sub-skill directory. Frontmatter, routing, and self-references are fixed in follow-up commits. Refs: microsoft#1827
Rewrite frontmatter name and description (folded YAML per tests/AGENTS.md) with explicit DO-NOT-USE routing to the azure-kubernetes parent and the automatic-readiness sibling. Refs: microsoft#1827
The template uses ENTRYPOINT but two header comments still said CMD, the same inconsistency review flagged and fixed on the dotnet template. Refs: microsoft#1827
Add a Related-skills entry and a disambiguation note so cluster-vs-app deploy intent routes to azure-kubernetes-app-deploy. Refs: microsoft#1827
Six Vally stimuli (routing, boundary, output, workspace-fixture) covering the app-deploy sub-skill, plus a minimal Express fixture app. Grades on the parent skill name; replaces the deprecated Jest suite from microsoft#1827. Refs: microsoft#1827
There was a problem hiding this comment.
Pull request overview
Adds an app deployment workflow as a nested sub-skill (azure-kubernetes-app-deploy) under the existing azure-kubernetes skill, plus accompanying templates/references/knowledge packs and Vally eval coverage. This aligns with the stated intent to treat “deploy to AKS” as part of the broader AKS skill family rather than a separate top-level skill.
Changes:
- Adds the new nested
azure-kubernetes-app-deployskill (SKILL.md, workflow docs, references, knowledge packs, and templates). - Updates the parent
azure-kubernetesskill to clearly route “deploy app to existing cluster” requests to the new sub-skill. - Extends
evals/azure-kubernetes/eval.yamlwith new stimuli + adds a small workspace fixture app for deployment guidance tests.
Reviewed changes
Copilot reviewed 45 out of 45 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| plugin/skills/azure-kubernetes/SKILL.md | Links and routing note pointing “app deploy” users to the new nested sub-skill. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/SKILL.md | New sub-skill definition for deploying apps to existing AKS clusters. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/phases/quick-deploy.md | End-to-end quick-deploy workflow (detect → generate → validate safeguards → deploy → verify). |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/references/detection.md | Framework/port/health detection reference tables. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/references/safeguards.md | Deployment Safeguards DS001–DS013 reference checklist. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/references/workload-identity.md | Workload Identity primer + per-service patterns and examples. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/references/rollback.md | Rollback guidance for common failure modes. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/knowledge-packs/frameworks/spring-boot.md | Spring Boot-specific container + probe + sizing guidance. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/knowledge-packs/frameworks/nextjs.md | Next.js-specific container + probe + writable-path guidance. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/knowledge-packs/frameworks/nestjs.md | NestJS-specific container + probe + operational guidance. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/knowledge-packs/frameworks/go.md | Go-specific container + probe + sizing guidance. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/knowledge-packs/frameworks/flask.md | Flask-specific container + probe + secrets guidance. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/knowledge-packs/frameworks/fastapi.md | FastAPI-specific container + probe + DB URL guidance. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/knowledge-packs/frameworks/express.md | Express/Fastify container + probe + DB env var guidance. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/knowledge-packs/frameworks/django.md | Django-specific container + health + collectstatic guidance. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/knowledge-packs/frameworks/aspnet-core.md | ASP.NET Core container + health + data-protection guidance. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/mermaid/summary-dashboard.md | Terminal-friendly post-deploy summary template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/mermaid/architecture-diagram.md | Mermaid architecture diagram template for deployed app + services. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/k8s/serviceaccount.yaml | Workload Identity-enabled ServiceAccount template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/k8s/service.yaml | ClusterIP Service template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/k8s/pdb.yaml | PodDisruptionBudget template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/k8s/networkpolicy.yaml | NetworkPolicy template restricting ingress to ingress/gateway namespace. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/k8s/namespace.yaml | Namespace template for app isolation. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/k8s/ingress.yaml | Web App Routing Ingress template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/k8s/httproute.yaml | Gateway API HTTPRoute template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/k8s/hpa.yaml | HPA template (autoscaling/v2). |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/k8s/gateway.yaml | Gateway API Gateway template (Istio gateway class). |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/k8s/deployment.yaml | Deployment template aligned to DS001–DS013 guidance. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/k8s/configmap.yaml | ConfigMap template for non-secret configuration. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/github-actions/deploy.yml | Example CI/CD workflow for build/push/deploy to AKS with OIDC auth. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/dockerfiles/rust.dockerignore | Rust .dockerignore template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/dockerfiles/rust.Dockerfile | Rust production Dockerfile template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/dockerfiles/python.dockerignore | Python .dockerignore template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/dockerfiles/python.Dockerfile | Python production Dockerfile template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/dockerfiles/node.dockerignore | Node.js .dockerignore template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/dockerfiles/node.Dockerfile | Node.js production Dockerfile template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/dockerfiles/java.dockerignore | Java .dockerignore template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/dockerfiles/java.Dockerfile | Java (Spring Boot/Maven) production Dockerfile template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/dockerfiles/go.dockerignore | Go .dockerignore template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/dockerfiles/go.Dockerfile | Go production Dockerfile template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/dockerfiles/dotnet.dockerignore | .NET .dockerignore template. |
| plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/templates/dockerfiles/dotnet.Dockerfile | .NET (ASP.NET Core) production Dockerfile template. |
| evals/azure-kubernetes/fixture/app/server.js | Express fixture app used by the new workspace-fixture stimulus. |
| evals/azure-kubernetes/fixture/app/package.json | Express fixture app dependencies for the workspace-fixture stimulus. |
| evals/azure-kubernetes/eval.yaml | Adds six new Vally stimuli covering routing, boundary, output, and workspace fixture behavior. |
- SKILL.md: use inline double-quoted description (the repo frontmatter
validator rejects >- folded scalars); the earlier folded-YAML premise
was incorrect for this repo.
- configmap.yaml: make data an explicit empty map ({}) so Kubernetes
accepts the ConfigMap (bare data: parses as null).
- deploy.yml: exclude <image> from the angle-bracket placeholder check
so the workflow reaches the image-substitution step instead of failing
on the intentionally-retained <image> token.
Refs: microsoft#1827
Jon Gallant (jongio)
left a comment
Jon Gallant (jongio)
left a comment
There was a problem hiding this comment.
The CI eval failure is pre-existing (azure-compute orphan files, not from this PR). The azure-kubernetes skill and eval both pass.
Two concerns beyond my earlier comment about content volume:
Safeguards duplication: references/safeguards.md (DS001-DS013) overlaps with the constraint spec already bundled in the sibling azure-kubernetes-automatic-readiness sub-skill. Consider referencing the existing constraint spec rather than maintaining a second copy of safeguard documentation within the same parent skill tree.
Knowledge pack maintenance: 9 framework-specific guides totaling ~2,060 lines (django, express, flask, fastapi, spring-boot, nextjs, nestjs, aspnet-core, go). Each contains Dockerfile patterns, health endpoint setup, database config, security context, and resource sizing. This framework knowledge changes with each major version. What's the plan for keeping these current? If they drift, the skill will generate outdated Dockerfiles or incorrect health endpoint configs.
The three Copilot review bot comments on this PR (frontmatter format, configmap data: {}, deploy.yml placeholder validation) appear to be incorrect. The description is an inline string already, data: {} is a valid empty map (not null), and <image> is explicitly excluded from the placeholder grep.
Fair point -- let me see if i can genericize them a bit more to still be valuable without requiring constant updates |
Jon Gallant (jongio)
left a comment
Jon Gallant (jongio)
left a comment
There was a problem hiding this comment.
Formalizing the outstanding concern as a blocking request since you acknowledged it needs work but haven't pushed changes yet.
The framework knowledge packs (9 files, ~2,060 lines) contain version-pinned Dockerfile patterns, specific health endpoint implementations, database connection snippets, and security context recommendations. This content has a short shelf life. When Django 6, Spring Boot 4, or Next.js 16 ship, these files become actively misleading rather than helpful.
You mentioned you'd genericize them. Until that's done, this is blocking because deploying with stale framework advice (wrong base image tags, deprecated health check patterns, outdated security contexts) is worse than having no framework-specific advice at all.
Suggested direction: keep the detection logic and K8s manifest templates (those are framework-agnostic and stable), but reduce framework packs to a brief pointer table (framework, default port, health path, signal files) rather than full Dockerfile recipes and config examples. The Dockerfile templates in emplates/dockerfiles/ already cover the build patterns generically.
Replace pinned base-image versions with <LATEST_STABLE_*> placeholders resolved at generation time. Refs: microsoft#2696
Single source for base-image selection and <LATEST_STABLE_*> resolution; documents the Microsoft/Azure Linux option. Refs: microsoft#2696
Remove inline Dockerfiles and pinned versions; keep framework deltas (collectstatic, init-container migrations, asyncpg, writable paths). Add pointer table. Refs: microsoft#2696
Remove inline Dockerfiles and pinned versions; keep framework deltas (Fastify 0.0.0.0 bind, Next standalone + ISR cache mount, Nest shutdown hooks). Add pointer table. Refs: microsoft#2696
Remove inline Dockerfiles and pinned versions; keep framework deltas (Spring startupProbe, Go CGO/distroless + graceful shutdown, ASP.NET Data Protection keys). Add pointer table. Refs: microsoft#2696
Point to the sibling constraint spec as source of truth; keep only the deploy-time auto-fix checklist. Refs: microsoft#2696
Resolve <LATEST_STABLE_*> at generation time; clarify DS009-safe major-tag pinning; trim duplicated pack content. Refs: microsoft#2696
Re-add the deployment.yaml image-tag timing note and the RBAC admin-create alternative trimmed during token reduction. Refs: microsoft#2696
Move detail into references; add base-images.md to the reference list. Refs: microsoft#2696
Fix the relative path to the sibling constraint spec (../ -> ../../) and de-pin a residual runtime-deps version in a dotnet template comment. Refs: microsoft#2696
Dismissing: this review was incorrectly posted as changes-requested due to an automation bug. The findings remain valid as comments.
Jon Gallant (jongio)
left a comment
Jon Gallant (jongio)
left a comment
There was a problem hiding this comment.
Two items from the prior review cycle remain unresolved:
-
Knowledge pack genericization still pending. The 9 framework packs (~2,060 lines) pin specific base image versions (node:22, python:3.12, openjdk:21) and contain full Dockerfile recipes that will drift with major framework releases. Tom Gamble (@gambtho) acknowledged this needs work in the conversation thread but no changes landed. Suggestion: add a
Last validated: YYYY-MMline to each pack header so future maintainers know when to audit, and consider reducing the Dockerfile sections to a brief "key decisions" table (base image choice rationale, signal handling approach, writable paths) rather than full copy-paste recipes. The actual Dockerfile templates intemplates/dockerfiles/already serve as the canonical artifact. -
Gateway API CRD version pinned to v1.0.0 (see inline comment on quick-deploy.md).
Replace the pinned gateway-api v1.0.0 release URL with the releases/latest/download form so the skill installs current stable CRDs at runtime instead of an Oct-2023 version. Refs: microsoft#2696
Jon Gallant (jongio)
left a comment
Jon Gallant (jongio)
left a comment
There was a problem hiding this comment.
One non-blocking nit on the new base-images doc (inline below). The placeholder pattern and framework-pack reduction both look correct.
Thoughts on this approach in general- should be less maintenance, but it's not as concise as what you suggested? I think there is some value in being a bit more descriptive to help the llm make good choices, but the size is a tradeoff. Happy to slim it down to what you suggested if you feel strongly Jon Gallant (@jongio) |
Note in base-images.md why Go/Rust runtime stages keep the literal gcr.io/distroless/*-debian12 names instead of a <LATEST_STABLE_*> placeholder, so the build/runtime asymmetry is not mistaken for a bug. Refs: microsoft#2696
Jon Gallant (jongio)
left a comment
Jon Gallant (jongio)
left a comment
There was a problem hiding this comment.
Re the verbosity question: the descriptive approach works for LLM consumption. Explicit rationale (like the distroless note) prevents the model from generating wrong fixes where an implicit convention would be ambiguous. The extra lines are justified when the reasoning isn't obvious from structure alone. Don't slim it down further.
|
chandraneel Jon Gallant (@jongio) ok to approve this? |
There was a problem hiding this comment.
☕️👍 for the eval specs JasonYeMSFT (@JasonYeMSFT) for eyes. Thank you!
Resolves the conflict with main's repository restructure, which moved
plugin/skills/ -> plugins/azure-skills/skills/ and evals/<name>/ ->
evals/azure-skills/<name>/.
Git's rename detection merged the files this branch modified in place,
but the files it *added* had no counterpart on main and were left
stranded at the now-deleted paths. Relocated them to the new layout:
plugin/skills/azure-kubernetes/azure-kubernetes-app-deploy/
-> plugins/azure-skills/skills/azure-kubernetes/azure-kubernetes-app-deploy/
evals/azure-kubernetes/fixture/app/
-> evals/azure-skills/azure-kubernetes/fixture/app/
The safeguards.md reference to the sibling automatic-readiness spec is
relative and stays valid, since both sub-skills moved together.
* docs(azure-kubernetes): distinguish cluster provisioning from app-deploy workflow (Azure Skills 1.2.4) Add scope boundary to azure-kubernetes.md: skill is for AKS cluster planning/provisioning/configuration; point to azure-kubernetes-app-deploy for deploying applications to an existing cluster. - Add boundary sentence in 'What it provides' - Update 'When to use this skill' intro with explicit scope qualifier - Add app-deploy pointer after the use-case list - Update ms.date to 08/23/2026 and ms.custom to skill-version-1.2.4 Upstream: microsoft/GitHub-Copilot-for-Azure#2696 ADO: 600830 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(azure-kubernetes): correct ms.custom to skill-version-1.2.24 (was 1.2.4 typo) Update ms.custom metadata to skill-version-1.2.24 matching Azure Skills release 1.2.24 / ADO 617962. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update azure-kubernetes.md * Update description in azure-kubernetes.md Removed specific details from the description for clarity. * Fix link formatting for Azure Kubernetes Service * Update Azure Kubernetes Service link to relative path --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Description
Folds the
deploy-to-akscapability from #1827 into the existingazure-kubernetesskill as a nested sub-skill,azure-kubernetes-app-deploy,directly addressing the review request to make deploy "a workflow within
azure-kubernetes" rather than a separate top-level skill.
Structure mirrors the existing
azure-kubernetes-automatic-readiness/sub-skill:no separate
version.json(parentpathFilterscovers the subtree), no newtests/skills.jsonentry, and tests added as Vally stimuli in the parent'sevals/azure-kubernetes/eval.yaml.The
app-deployname makes the cluster-vs-app boundary explicit:azure-kubernetes— provision/configure the clusterazure-kubernetes-automatic-readiness— assess migration to AKS Automaticazure-kubernetes-app-deploy— deploy an app to an existing clusterReview comments from #1827
original branch (configmap
data:, deployment replicas/HPA note, dotnet/javaDockerfile headers, workload-identity imports and "Microsoft Entra ID"
rename).
tests/deploy-to-aks/*Jest comments (repo migrated to Vally). The.gitignore/settings.local.jsonhygiene items are resolved by omission.Testing
Six Vally stimuli (routing, routing boundary, output, workspace-fixture) added
to
evals/azure-kubernetes/eval.yaml, grading on theazure-kubernetesskillinvocation.
checkCopilotCliCharBudgetpasses (19315/20000; the nestedsub-skill description is not counted against the top-level budget).
Supersedes #1827.