The integration of Custom Resource Definitions (CRDs) within the Pulumi ecosystem represents a critical bridge between the extensibility of the Kubernetes API and the safety of strongly typed infrastructure-as-code. In standard Kubernetes environments, CRDs allow operators to extend the API by defining custom objects that serve specific purposes, such as managing SSL certificates via cert-manager or configuring service meshes via Istio. While Pulumi provides native capabilities to manage these CustomResources directly, doing so typically involves using untyped structures. Because every CRD schema is unique and often diverges significantly in structure, these resources are untyped by default. This absence of strong typing manifests as a significant operational hurdle, particularly when dealing with complex YAML schemas that may span thousands of lines. To resolve this, the crd2pulumi CLI tool has been developed to translate Kubernetes CRD YAML schemas into typed Pulumi SDK classes. By reading the OpenAPI schema embedded within a CRD, crd2pulumi generates language-specific classes that empower developers with IDE autocompletion and compile-time type checking, thereby reducing the likelihood of deployment errors and accelerating the development lifecycle.
The Architecture of crd2pulumi
The crd2pulumi tool is designed as a command-line interface (CLI) utility that bridges the gap between the loosely typed world of Kubernetes YAML and the strongly typed environment of Pulumi SDKs. The primary function of the tool is to consume a CustomResourceDefinition YAML file and output the corresponding SDK classes for the user's chosen programming language.
The necessity of this tool becomes apparent when analyzing the scale of modern Kubernetes operators. For example, popular CRDs such as those used by Istio or cert-manager are characterized by immense complexity. Manually mapping these properties into a Pulumi program without type safety is a tedious process prone to human error. crd2pulumi automates this mapping process by extracting the OpenAPI schema from the CRD, ensuring that the generated classes mirror the exact requirements of the Kubernetes API server. This allows the developer to shift the discovery of errors from the deployment phase (where a pulumi up would fail due to an invalid field) to the coding phase (where the IDE flags a type mismatch).
Installation and Environmental Setup
Depending on the operating system and the user's preference for package management, there are several ways to install crd2pulumi.
MacOS Installation
For users on MacOS, the most streamlined method is utilizing the Homebrew package manager. Pulumi maintains a dedicated tap for its utilities.
- Install via Homebrew:
brew install pulumi/tap/crd2pulumi
This method ensures that the binary is placed in a standard path and can be updated using standard Homebrew commands.
Windows Installation
On Windows systems, crd2pulumi can be managed through the Chocolatey package manager. Version 1.2.0 of the package is available.
- Installation: This is handled via the Chocolatey CLI from the command line or PowerShell.
- Upgrade: The package can be updated using the standard Chocolatey upgrade command.
- Uninstallation: The package can be removed using the Chocolatey uninstall command.
For organizational deployments using Chocolatey, users can integrate the tool into internal repositories via a proxy NuGet repository on Nexus, Artifactory Pro, or a proxy Chocolatey repository on ProGet by pointing the upstream to https://community.chocolatey.org/api/v2/.
Manual Binary Installation
Users who prefer not to use a package manager can download the compiled binaries directly from the GitHub releases page. These binaries are pre-compiled and ready for execution upon being added to the system's execution path.
Development Setup and Compilation
For individuals who wish to contribute to the tool's development or build it from source, a Go environment is required. crd2pulumi utilizes Go modules for dependency management.
- Prerequisites: Go must be installed on the host system.
- Build Command: To build the binary and install it into the
$GOPATH/bindirectory, the following command is used:go build -ldflags="-X github.com/pulumi/crd2pulumi/gen.Version=dev" -o $GOPATH/bin/crd2pulumi main.go
The use of the ldflags argument is mandatory during the build process as it dynamically sets the version of crd2pulumi at the time of compilation. Once the build is complete, the resulting binary is stored in $GOPATH/bin. If this directory is not already present in the system's PATH environment variable, the user must manually move the binary to a directory that is on the path or update the environment variables to include it.
Technical Usage and Command Specifications
The crd2pulumi CLI provides a versatile set of flags and commands to support multiple programming languages and output configurations.
Command Syntax
The general structure for executing the tool is as follows:
crd2pulumi [-dgnp] [--nodejsPath path] [--pythonPath path] [--dotnetPath path] [--goPath path] [--javaPath path] <crd1.yaml> [crd2.yaml ...] [flags]
The tool also supports basic command structures for utility tasks:
help: Provides information about available commands and flags.version: Outputs the current version number of the installedcrd2pulumitool.
Language-Specific Flags
The tool supports a variety of languages, each with its own set of flags for generation and path configuration.
.NET Generation:
-dor--dotnet: Triggers the generation of .NET classes.--dotnetName: Specifies the name of the generated .NET package, which defaults to "crds".--dotnetNamespace: Defines the namespace for the generated .NET package.--dotnetPath: Sets the optional output directory for the .NET files.
Go Generation:
-gor--go: Triggers the generation of Go classes.--goName: Specifies the name of the generated Go package, which defaults to "crds".--goPath: Sets the optional output directory for the Go files.
Java Generation:
--javaPath: Specifies the output directory for the generated Java classes.
Node.js and Python Generation:
--nodejsPath: Specifies the output directory for Node.js files.--pythonPath: Specifies the output directory for Python files.
A key operational detail is that simply providing a language-specific output path (such as --pythonPath or --nodejsPath) is sufficient to trigger the code generation for that language. In such cases, the shorthand flags (like -p or -n) become redundant.
Practical Execution Examples
The tool can be used for a single file or multiple files simultaneously, and it can even pull schemas directly from remote URLs.
- Generating for Node.js:
crd2pulumi --nodejs crontabs.yaml - Generating for multiple languages (dotnet, go, nodejs, python) for multiple files:
crd2pulumi -dgnp crd-certificates.yaml crd-issuers.yaml crd-challenges.yaml - Generating for Python and Node.js with specific output paths:
crd2pulumi --pythonPath=crds/python/istio --nodejsPath=crds/nodejs/istio crd-all.gen.yaml crd-mixer.yaml crd-operator.yaml - Generating from a remote URL:
crd2pulumi --pythonPath=crds/python/gke https://raw.githubusercontent.com/GoogleCloudPlatform/gke-managed-certs/master/deploy/managedcertificates-crd.yaml
Implementation in Pulumi Programs
Once the typed classes are generated, they can be integrated into Pulumi stacks. This process replaces the use of generic CustomResource objects with specific, typed classes.
Java Implementation Example
In a Java environment, the generated classes are imported and used within the Pulumi.run block. The following demonstrates the instantiation of a CronTab resource based on a generated schema:
java
package com.example;
import com.pulumi.Pulumi;
public class MyStack {
public static void main(String[] args) {
Pulumi.run(ctx -> {
// Register a CronTab CRD (Coming Soon - see https://www.pulumi.com/registry/packages/kubernetes/api-docs/yaml/configfile/)
// Instantiate a CronTab resource.
var cronTabInstance = new com.pulumi.crds.stable.v1.CronTab("cronTabInstance",
com.pulumi.crds.stable.v1.CronTabArgs.builder()
.metadata(com.pulumi.kubernetes.meta.v1.inputs.ObjectMetaArgs.builder()
.name("my-new-cron-object")
.build())
.spec(com.pulumi.kubernetes.stable.v1.inputs.CronTabSpecArgs.builder()
.cronSpec("* * * * */5")
.image("my-awesome-cron-image")
.build())
.build());
});
}
}
To generate the classes for this Java example, the following command is used:
crd2pulumi --javaPath ./crontabs resourcedefinition.yaml
After the code is written, the deployment is performed using the standard command:
pulumi up
.NET Implementation Example
In .NET, the generated classes provide a similarly typed experience. The resource instantiation follows this pattern:
csharp
ConfigFileArgs{
File = "resourcedefinition.yaml"
}
);
// Instantiate a CronTab resource.
var cronTabInstance = new Pulumi.Crds.Stable.V1.CronTab("cronTabInstance",
new Pulumi.Kubernetes.Types.Inputs.Stable.V1.CronTabArgs{
Metadata = new ObjectMetaArgs{
Name = "my-new-cron-object"
},
Spec = new Pulumi.Kubernetes.Types.Inputs.Stable.V1.CronTabSpecArgs{
CronSpec = "* * * * */5",
Image = "my-awesome-cron-image"
}
});
}
}
A critical troubleshooting note for .NET users: if an error occurs during pulumi up regarding a Duplicate 'global::System.Runtime.Versioning.TargetFrameworkAttribute' attribute, the user should delete the crontabs/bin and crontabs/obj folders to resolve the conflict.
The Pulumi Kubernetes Operator
Beyond the generation of SDK classes for use in programs, Pulumi provides the Pulumi Kubernetes Operator. This is a Kubernetes controller designed to manage Pulumi infrastructure deployments using native Kubernetes resources and patterns.
The Pulumi Kubernetes Operator enables a fully declarative infrastructure management model. It achieves this by extending the Kubernetes API with its own set of Custom Resource Definitions (CRDs) specifically for Pulumi stacks. This allows the Kubernetes cluster itself to act as the orchestrator for Pulumi deployments, treating the Pulumi stack as a custom resource that can be managed, updated, and monitored using standard kubectl commands and Kubernetes lifecycle events.
Comparison of Resource Handling
The following table compares the experience of managing Custom Resources in Pulumi with and without the use of crd2pulumi.
| Feature | Standard CustomResource | crd2pulumi Generated Resource |
|---|---|---|
| Type Safety | Untyped / Generic | Strongly Typed |
| IDE Support | Basic text completion | Full Autocomplete |
| Error Detection | At Deployment (Runtime) | At Compilation (Build time) |
| Schema Discovery | Manual YAML Review | Integrated SDK Classes |
| Developer Velocity | Slower due to manual mapping | Faster due to typed arguments |
Analysis of Technical Impact
The introduction of crd2pulumi fundamentally changes the developer's interaction with the Kubernetes API. By transforming the OpenAPI schema of a CRD into a language-specific SDK, the tool removes the "guesswork" associated with infrastructure as code.
The real-world consequence for the user is a significant reduction in the feedback loop. In a traditional untyped workflow, a developer might spend hours configuring a complex Istio gateway, only to have the deployment fail because of a typo in a nested YAML field. With crd2pulumi, that typo is caught by the IDE's red squiggly lines or by the compiler before the code is even committed.
Furthermore, this approach integrates seamlessly with the Pulumi Kubernetes Operator. While crd2pulumi helps in writing the code that defines the resources, the Operator ensures that these resources are managed natively within the cluster. Together, they create an ecosystem where Kubernetes' extensibility (via CRDs) is matched by Pulumi's programming power (via strong typing), resulting in an infrastructure management layer that is both flexible and robust. The ability to target multiple languages (Go, Java, Python, Node.js, .NET) ensures that regardless of the team's primary stack, they can leverage the full power of Kubernetes' custom resources without sacrificing the safety of their preferred programming language.