You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Document Pulumi Kubernetes Operator v2.1.0, v2.2.0, and v2.3.0 features (#16672)
* Document Pulumi Kubernetes Operator v2.3.0 features
Add documentation for preview mode and structured configuration features
introduced in v2.3.0. Update Helm installation to reference v2.3.0.
Changes:
- Update Helm installation version from v2.0.0 to v2.3.0
- Add "Preview mode" section with explanation and YAML example
- Add "Structured configuration" section with inline and ConfigMap examples
- Update table of contents with new sections
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <[email protected]>
* Add v2.1.0 and v2.2.0 feature documentation
Document features introduced in v2.1.0 and v2.2.0 releases that were
missing from the operator documentation.
v2.1.0 features:
- Pulumi ESC integration with spec.envs field
- Update template customization reference
- Retry configuration with spec.retryMaxBackoffDurationSeconds
v2.2.0 features:
- Dynamic environment variables via $PULUMI_ENV file
Changes:
- Add "Use Pulumi ESC for centralized configuration" section with example
- Enhance "Stack Configuration Values" with retry and update template info
- Enhance "Environment Variables" with $PULUMI_ENV file support and example
- Update table of contents
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <[email protected]>
---------
Co-authored-by: Claude <[email protected]>
[Pulumi ESC (Environments, Secrets, and Configuration)][pulumi-esc] provides centralized management of secrets and configuration. You can attach ESC environments to Stack objects to access shared configuration and secrets across multiple stacks.
167
+
168
+
Use the `spec.envs` field to specify one or more ESC environment names:
169
+
170
+
```yaml
171
+
apiVersion: pulumi.com/v1
172
+
kind: Stack
173
+
metadata:
174
+
name: my-app
175
+
spec:
176
+
serviceAccountName: pulumi
177
+
stack: my-org/my-app/prod
178
+
projectRepo: https://github.com/example/app
179
+
branch: main
180
+
envs:
181
+
- prod-shared-config
182
+
- aws-credentials
183
+
envRefs:
184
+
PULUMI_ACCESS_TOKEN:
185
+
type: Secret
186
+
secret:
187
+
name: pulumi-api-secret
188
+
key: accessToken
189
+
```
190
+
191
+
ESC environments are accessed using your Pulumi access token. The configuration and secrets from these environments become available to your Pulumi program automatically.
192
+
193
+
[pulumi-esc]: https://www.pulumi.com/docs/esc/
194
+
161
195
## Create a Stack Resource
162
196
163
197
The `Stack` Resource encapsulates a Pulumi project to provision infrastructure resources such as cloud VMs, object storage, and Kubernetes clusters and their workloads.
@@ -572,17 +606,115 @@ The value may be a literal value or may be a reference to a Kubernetes `Secret`.
572
606
Use the `spec.secretsProvider` field to use an alternative encryption provider.
573
607
See ["Initializing a stack with alternative encryption"][iac-secrets-provider] for more information.
574
608
609
+
Use the `spec.retryMaxBackoffDurationSeconds` field to control the maximum backoff duration for failed updates. This defaults to one update attempt per day (86400 seconds) but can be adjusted for faster retry cycles during development.
610
+
611
+
To customize the retention of Update objects created by the Stack controller, use the `spec.updateTemplate` field to set labels, annotations, and TTL (time-to-live) policies. See the [Update CR documentation][pko-updates] for details.
In addition to string values, Stack configuration supports complex data types including objects, arrays, numbers, and booleans. This enhancement allows you to express sophisticated configuration structures inline in your Stack manifests or load them from ConfigMaps with automatic JSON parsing.
622
+
623
+
This feature requires Pulumi CLI v3.202.0 or later in your workspace pods. The operator provides automatic version detection with clear upgrade guidance when needed.
624
+
625
+
Here's an example with inline structured configuration:
626
+
627
+
```yaml
628
+
apiVersion: pulumi.com/v1
629
+
kind: Stack
630
+
metadata:
631
+
name: my-app
632
+
spec:
633
+
serviceAccountName: pulumi
634
+
stack: my-org/my-app/prod
635
+
projectRepo: https://github.com/example/app
636
+
branch: main
637
+
config:
638
+
# String values (existing behavior)
639
+
environment: "production"
640
+
641
+
# Objects (NEW)
642
+
database:
643
+
host: "db.example.com"
644
+
port: 5432
645
+
ssl: true
646
+
647
+
# Arrays (NEW)
648
+
regions: ["us-west-2", "us-east-1", "eu-west-1"]
649
+
650
+
# Numbers and booleans (NEW)
651
+
maxConnections: 100
652
+
enableCaching: true
653
+
envRefs:
654
+
PULUMI_ACCESS_TOKEN:
655
+
type: Secret
656
+
secret:
657
+
name: pulumi-api-secret
658
+
key: accessToken
659
+
```
660
+
661
+
You can also reference ConfigMaps for complex configurations using the `json: true` flag:
662
+
663
+
```yaml
664
+
apiVersion: v1
665
+
kind: ConfigMap
666
+
metadata:
667
+
name: app-settings
668
+
data:
669
+
database.json: |
670
+
{
671
+
"host": "db.example.com",
672
+
"port": 5432,
673
+
"maxConnections": 100
674
+
}
675
+
---
676
+
apiVersion: pulumi.com/v1
677
+
kind: Stack
678
+
metadata:
679
+
name: my-app
680
+
spec:
681
+
serviceAccountName: pulumi
682
+
stack: my-org/my-app/prod
683
+
projectRepo: https://github.com/example/app
684
+
branch: main
685
+
configRefs:
686
+
database:
687
+
name: app-settings
688
+
key: database.json
689
+
json: true # Parse as JSON
690
+
```
691
+
692
+
Note that Secrets are not a supported source of structured configuration values.
693
+
579
694
### Environment Variables
580
695
581
696
Use the `spec.envRefs` field to set environment variables for the Pulumi program,
582
697
such as `PULUMI_ACCESS_TOKEN` or `AWS_SECRET_ACCESS_KEY`.
583
698
584
699
Values may be literals or based on the contents of a `ConfigMap` or `Secret` object.
585
700
701
+
You can also set environment variables dynamically through init containers by writing to the `$PULUMI_ENV` file. Environment variables set this way affect the Pulumi CLI during deployment operations:
The value of the annotation is arbitrary, and we recommend using a timestamp.
627
759
760
+
### Preview mode
761
+
762
+
Preview mode enables you to run Pulumi stacks in dry-run fashion, allowing you to visualize what infrastructure changes would occur without actually applying them. When `spec.preview` is set to `true`, the operator runs `pulumi preview` instead of `pulumi up`.
763
+
764
+
This is useful for:
765
+
766
+
- Validating infrastructure changes before deployment
767
+
- Comparing different configurations using multiple Stack resources pointing to the same Pulumi stack
768
+
- Creating tick-tock rollout patterns where you toggle preview mode on and off
769
+
770
+
Here's an example Stack with preview mode enabled:
771
+
772
+
```yaml
773
+
apiVersion: pulumi.com/v1
774
+
kind: Stack
775
+
metadata:
776
+
name: my-infrastructure-preview
777
+
spec:
778
+
serviceAccountName: pulumi
779
+
stack: my-org/my-project/prod
780
+
projectRepo: https://github.com/example/infra
781
+
branch: feature-branch
782
+
preview: true # Only runs pulumi preview
783
+
envRefs:
784
+
PULUMI_ACCESS_TOKEN:
785
+
type: Secret
786
+
secret:
787
+
name: pulumi-api-secret
788
+
key: accessToken
789
+
```
790
+
791
+
The Stack's Ready condition indicates preview success, and status includes preview links, standard output, and program outputs—all without making actual infrastructure changes.
792
+
628
793
## Use With Argo CD
629
794
630
795
We can use ArgoCD in combination with PKO to manage the lifetime of the Stack via the GitOps paradigm. This gives you the ability to use the ArgoCD UI or CLI to interact with the Stack, and to allow ArgoCD to reconcile changes to the Stack specification. The Pulumi Kubernetes Operator handles the details.
0 commit comments