kargo with pko for change management

[lichtie]

Proposed changes

Add a blog post about using PKO with Kargo for change management

Unreleased product version (optional)

Related issues (optional)

[claude]

Documentation Review

I've reviewed PR #16669 and found several issues that need to be addressed before merging. Overall, the blog post provides valuable technical content about integrating PKO with Kargo for change management, but there are style, consistency, and accuracy issues to fix.

---

Issues Found

Critical Issues

1. Title exceeds 60-character limit (index.md:2)

The title "Change Management with the Pulumi Kubernetes Operator and Kargo" is 65 characters, exceeding the strict 60-character SEO limit specified in BLOGGING.md.

Suggestion:

title: "Change Management with PKO and Kargo"
h1: "Change Management with the Pulumi Kubernetes Operator and Kargo"

Add allow_long_title: true if you want to keep the longer H1 display.

---

2. Missing <!--more--> break (index.md:15)

The blog post is missing the required <!--more--> break after the first paragraph for proper display on the blog home page (per BLOGGING.md checklist).

Suggestion:

The [Pulumi Kubernetes Operator](https://www.pulumi.com/docs/iac/guides/continuous-delivery/pulumi-kubernetes-operator/) enables you to manage Pulumi stacks as Kubernetes resources, but it doesn't provide much guidance on change management. [Kargo](https://kargo.io/) fills this gap by providing controlled, staged promotions with verification steps. Together, they let you keep your infrastructure defined in Pulumi while managing multi-environment rollouts in a systematic way.

<!--more-->

## What you can do with Argo CD, PKO, and Kargo

---

Style and Consistency Issues

3. Inconsistent heading capitalization (index.md:19, 32)

Several H2 headings use Title Case instead of Sentence case as required by STYLE-GUIDE.md.

Issues:

• Line 19: "What you can do with Argo CD, PKO, and Kargo" ✅ (correct)
• Line 32: "What is Kargo" should be "What Kargo is" or "About Kargo"
• Line 48: "Example architecture" ✅ (correct)

Suggestion for line 32:

## About Kargo

---

4. Inconsistent product naming (throughout)

The blog post uses "Pulumi Kubernetes Operator" and "PKO" interchangeably without establishing the acronym properly at first use.

Suggestion for index.md:15:

The [Pulumi Kubernetes Operator (PKO)](https://www.pulumi.com/docs/iac/guides/continuous-delivery/pulumi-kubernetes-operator/) enables you to manage Pulumi stacks as Kubernetes resources...

After establishing PKO as the acronym, it's fine to use it throughout.

---

5. Use of "click" instead of "select" (index.md:162)

Line 162 says "create a secret in your project through the Kargo UI" and instructs to "Navigate to your project" and "Go to Settings > Credentials." The style guide specifies using "select" instead of "click" and "navigate" instead of "go to."

Suggestion for index.md:160-167:

### Pulumi access token

Kargo needs access to the Pulumi API to verify that infrastructure deployments completed successfully. Create a secret in your project through the Kargo UI:

1. Navigate to your project in the Kargo UI
1. Navigate to **Settings** → **Credentials**
1. Select **Create a new credential** with:
   - Name: `pulumi-api-token`
   - Type: `Opaque`
   - Key: `PULUMI_ACCESS_TOKEN`
   - Value: Your Pulumi access token

Note: Also added proper navigation arrow (→) and bolded UI elements per style guide.

---

6. Ordered list items not starting with "1." (index.md:77-82)

The style guide requires all ordered list items to begin with "1." to minimize diff noise.

Current (index.md:77-82):

**cluster**: Creates a basic Amazon EKS cluster where everything will run.

**cluster-setup**: Installs the required dependencies including PKO, cert-manager, Argo CD, Argo Rollouts, and AWS Cognito for authentication.

**kargo**: Deploys Kargo via Helm and provides examples to set up the project with stages, approval gates, and analysis templates for the promotion pipeline.

Suggestion:

1. **cluster**: Creates a basic Amazon EKS cluster where everything will run.
1. **cluster-setup**: Installs the required dependencies including PKO, cert-manager, Argo CD, Argo Rollouts, and AWS Cognito for authentication.
1. **kargo**: Deploys Kargo via Helm and provides examples to set up the project with stages, approval gates, and analysis templates for the promotion pipeline.

---

7. Mixed list formatting in workflow description (index.md:52-65)

The workflow section uses a numbered list (1-6) but should use ordered list syntax with "1." for each item per style guide.

Current format uses:

1. **[Security Scanner repository]...**
1. **Kargo**: ...

This is actually correct! However, ensure consistency throughout.

---

Content and Accuracy Issues

8. Incomplete or vague phrasing (index.md:32)

"What is Kargo" as a heading is a bit abrupt. Consider "About Kargo" or "What Kargo is" for better flow.

---

9. Long paragraph in Dashboard section (index.md:68-69)

The Dashboard and Management section contains a very long paragraph (6+ sentences) that should be broken up per style guide recommendation of ≤3 sentences per paragraph.

Suggestion for index.md:68-69:

### Dashboard and Management

![Kargo Dashboard](kargo_dash.png)

The Kargo dashboard brings operational visibility to this entire workflow. The timeline view at the top shows every freight version moving through your pipeline, making it immediately clear which infrastructure code version is running in each environment and how long it has been there.

The flow diagram below maps out your complete promotion path with color-coded stages. You can see at a glance where changes are flowing smoothly and where they are waiting at approval gates or blocked by failed verifications.

Status indicators on each stage show real-time health information, eliminating the need to manually check multiple systems or run status commands. This single-pane view reduces context switching, speeds up troubleshooting when issues arise, and gives both operators and stakeholders a shared understanding of exactly what infrastructure is deployed where.

---

10. Missing alt text for images

While images are included, verify they have descriptive alt text. The current markdown shows:

• ![PKO and Kargo Architecture](PKO_Kargo_Architecture.png) ✅ (has alt text)
• ![Kargo Dashboard](kargo_dash.png) ✅ (has alt text)
• ![Kargo Approver Role Setup](kargo_approver_role_setup.png) ✅ (has alt text)

These are good, but could be more descriptive. Consider:

• "Architecture diagram showing the integration between PKO, Kargo, Argo CD, and Pulumi"
• "Screenshot of Kargo dashboard showing freight timeline and stage flow diagram"
• "Screenshot of Kargo UI showing approver role configuration with promote permissions"

---

Minor Issues

11. Inconsistent spacing around code blocks

Ensure blank lines before and after all code blocks for consistency.

---

12. Consider adding a canonical_url

If there's corresponding documentation for PKO + Kargo integration in the docs, consider adding a canonical_url frontmatter field per BLOGGING.md guidance.

---

Recommendations

1. Fix the title length issue (critical for SEO)
2. Add the <!--more--> break (required for blog home page display)
3. Fix heading capitalization to follow sentence case
4. Establish the PKO acronym at first use
5. Break up long paragraphs (especially in Dashboard section)
6. Update UI navigation language to use "select" and "navigate"
7. Consider more descriptive alt text for images
8. Verify the meta_image looks good and uses current logos

---

Positive Aspects

• Clear, technical explanation of a complex integration
• Good use of concrete examples with linked repositories
• Helpful diagrams and screenshots
• Well-structured progression from concepts to implementation
• Appropriate use of notes shortcode for additional information

---

The content is solid and valuable for users looking to implement change management with PKO and Kargo. Once these style and formatting issues are addressed, this will be a great addition to the Pulumi blog.

Please mention me (@claude) if you'd like additional reviews or help implementing these fixes!

[pulumi-bot]

Your site preview for commit c5d8e5a is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16669-c5d8e5a4.s3-website.us-west-2.amazonaws.com.

[pulumi-bot]

Your site preview for commit d4954af is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16669-d4954af1.s3-website.us-west-2.amazonaws.com.

[EronWright]

PKO Subject Matter Review ✅

I've reviewed the PKO-related technical content in this blog post. All claims are accurate.

Verified Technical Claims

Claim	Status
PKO manages Pulumi stacks as Kubernetes resources	✅ Correct
Kargo updates Stack with new Git reference, PKO reconciles	✅ Correct (spec.commit, spec.branch)
Preview stages run pulumi preview	✅ Correct (spec.preview: true)
Update stages run pulumi up	✅ Correct (default behavior)
Architecture: Kargo → manifests → Argo CD → PKO → Pulumi	✅ Valid GitOps pattern
Verification via Pulumi API	✅ Correct (status.lastUpdate.state)

Optional Enhancements

These would make the post more actionable but aren't blocking:

1. Preview mode Stack example: Consider showing spec.preview: true on a Stack manifest, since the post mentions "Preview stages run pulumi preview"

2. Analysis template snippet: The verification section describes what analysis templates do but doesn't show the YAML. Consider linking to the example in the repo or showing a snippet of the Pulumi API query.

3. Promotion mechanism: A brief example showing how Kargo updates spec.commit during promotion would complete the picture of how Kargo connects to PKO.

Great post! The integration pattern is valuable for teams managing multi-environment infrastructure rollouts.