How to Use the Command 'pulumi new' (with Examples)
The pulumi new command is a powerful tool in the Pulumi toolset, designed to help users create new infrastructure-as-code (IaC) projects effortlessly. Pulumi is a platform for building and managing cloud infrastructure with a variety of programming languages. By invoking pulumi new, you can initialize a new project based on different templates, which can come from either local or remote sources. This flexibility lets you tailor your infrastructure setup to your specific needs, whether you’re working with AWS, Azure, Google Cloud, or other environments.
Use Case 1: Choose a Template Interactively
Code:
pulumi new
Motivation:
When you are unsure of which template to use or want to explore different infrastructure configurations available, the interactive mode provided by pulumi new is invaluable. It allows you to browse through and select from a list of available templates directly in the command line interface, making the process of starting a new project both user-friendly and accessible for beginners and experienced developers alike.
Explanation:
In this use case, running pulumi new without specifying additional arguments triggers an interactive setup within your terminal. You will be presented with a list of available templates for various cloud environments and programming languages. This step-by-step assistance ensures that you can easily find and initialize the most suitable project configuration for your requirements, offering you the flexibility to choose optional features interactively.
Example Output:
Please enter your desired project name. This will be used in various places in the project, including in your Pulumi stack names.
Enter a value or leave blank to use "test":
Use Case 2: Create a Project from a Specific Template
Code:
pulumi new azure-python
Motivation:
If you know which template fits your project’s requirements, specifying a template directly with the pulumi new command saves time. By selecting, for example, azure-python, you leverage a pre-defined template that sets up a new Pulumi project using the Azure cloud with Python as the programming language. This is particularly useful when you have a clear understanding of the infrastructure and toolset you want to utilize.
Explanation:
Here, the argument azure-python specifies the template you wish to use. Pulumi maintains a collection of boilerplate projects for various cloud providers and languages, such as AWS with JavaScript, Azure with Python, etc. By providing this specific argument, Pulumi can bypass the interactive mode and quickly set up the basic structure and necessary files for a Python project targeting Azure.
Example Output:
Created a new Pulumi project in 'azure-python' with an `azure-python` template.
Use Case 3: Create a Project from a Local File
Code:
pulumi new path/to/templates/aws-typescript
Motivation:
In cases where you’ve developed custom templates or need to use a specific template stored locally, using pulumi new with a file path allows integration of custom setups or organization-specific standards. This method helps in maintaining consistency across multiple projects or teams, using a predefined infrastructure code scheme tailored to specific needs.
Explanation:
The argument path/to/templates/aws-typescript points to a local directory containing a Pulumi template. By specifying a path, Pulumi recognizes that it should use the files within that directory to scaffold the new project. This approach is often used for internal templates that embody best practices or conform to an organization’s coding principles.
Example Output:
Created a new Pulumi project in 'aws-typescript' using a local template.
Use Case 4: Create a Project from a Git Repository
Code:
pulumi new https://github.com/username/repository
Motivation:
Utilizing pulumi new with a Git repository URL allows developers to create a project based on a remote template. This is particularly beneficial for collaboration, as it offers a centralized way to share and reuse infrastructure configurations across different developers and teams. It simplifies the process of adopting community-driven templates or collaborating on project templates stored in repositories.
Explanation:
By providing a Git URL (e.g., https://github.com/username/repository), Pulumi pulls the specified repository content into the new project directory. This use case demonstrates the integration of version control systems into Pulumi’s workflow, enabling seamless sharing and updating of ready-made templates across multiple users.
Example Output:
Cloning into 'repository'...
Created a new Pulumi project in 'repository'.
Use Case 5: Use the Specified Secrets Provider with the Pulumi.com Backend
Code:
pulumi new --secrets-provider=passphrase
Motivation:
Security is a crucial aspect of infrastructure management. The pulumi new command with the --secrets-provider=passphrase argument sets up a project with a particular secrets provider that ensures your infrastructure’s sensitive data is handled securely. Specifying a secrets provider is ideal for complying with security policies or meeting requirements for encrypted state management.
Explanation:
The argument --secrets-provider=passphrase configures the secrets manager that Pulumi uses. In this case, the passphrase provider manages secrets with a passphrase-based encryption mechanism. This choice guarantees that any sensitive information in your project’s state, such as API keys or passwords, is encrypted and securely managed according to the specified backend strategy.
Example Output:
Created a new Pulumi project with a passphrase secrets provider.
Conclusion:
The pulumi new command is versatile, providing several ways to initialize a Pulumi project to suit various scenarios—from interactive template selection to specifying complex security configurations. Whether you’re starting with a predefined template or adopting a custom setup, pulumi new makes creating infrastructure-as-code projects efficient, accessible, and secure.
