Pulumi Blog: Docker

105 Ways to Run Containers: The Cloud Container Iceberg

Adam Gordon Bell — Tue, 03 Dec 2024 10:29:54 -0500

If a computer can be connected to the internet, someone has tried to run a container on it. From quantum computers to smart toasters, from phones in AWS racks to CI pipelines, there’s many ways to deploy containers. While most people only know about the mainstream cloud providers at the surface, there’s actually a vast world of increasingly unusual and specialized options beneath.

This guide serves two purposes: to showcase the surprising breadth of container options available today, and to help you understand the full spectrum of choices – from practical to very experimental. Whether you’re looking for production-ready solutions or just curious about what’s out there in the dark depths, you’ll find something interesting here.

Constraints

But first, we need ground rules for our container adventures. All listed items should:

Technically possible: Must work today with existing tech, even if the setup makes you question your life choices.
Runs real containers: OCI containers only. No JavaScript “containers” pretending to be the real thing.
Actually doable: You can set this up right now with a laptop and a credit card. No theoretical schemes allowed.

Above the iceberg – The usual suspects

These are the familiar faces of container orchestration—the ones you’d introduce to your parents. Reliable, well-documented, and about as exciting as watching paint dry.

Amazon Elastic Kubernetes Service (EKS)
Amazon Elastic Container Service (ECS)
AWS Fargate
Azure Kubernetes Service (AKS)
Google Kubernetes Engine (GKE)
Google Cloud Run
Amazon EC2
AWS App Runner
Azure App Service for Containers
Google Compute Engine with Containers

On the iceberg – The slightly less obvious

As we dip just below the surface, we find services like a rare B-side acoustic release from a big band. It’s not as mainstream but still a respectable choice for running your containers.

AWS Elastic Beanstalk – Deploy containers, debug YAML
Amazon Lightsail Containers – AWS with the guard rails on
Azure Container Apps – Serverless, but complicated
Google App Engine Flexible Environment – PaaS for Containerized Apps
Azure Container Instances (ACI) – Kubernetes without the chaos

The kubernetes multiverse – Because one Universe of k8s wasn’t enough

Diving deeper, we discover there’s an entire multiverse of regional and specialty K8s providers, helpfully cataloged by the CNCF. Think parallel universes, but instead of evil twins, you get slightly different container runtime implementations.

The Global Titans – The international tech giants couldn’t resist joining the K8s party: Huawei Cloud Container Engine, Tencent, and Baidu bring their own flavor of cloud-native orchestration to the mix. Add in Samsung, China Mobile KCS, JD Cloud, Inspur, and QingCloud, and you have enough options to start a diplomatic incident.
The European Union of Containers – Europeans take their container privacy seriously: IONOS and plusserver bring German engineering to K8s, OVH adds French flair, Exoscale offers Swiss precision, and STACKIT, SysEleven, WIIT, Gcore, and Previder ensure your containers comply with every possible EU regulation. Conoa Proact throws in some Swedish design principles for good measure.
The Asia-Pacific Pod Party – The APAC region isn’t missing out: NHN brings Korean optimization to your clusters, while ARDC Nectar and Catalyst let you run containers upside down in Australia and New Zealand. TKS Cloud Service ensures your containers can run anywhere from Tokyo to Tasmania.
The Specialists’ Society – For when regular K8s isn’t quirky enough: OKESTRO VIOLA orchestrates your containers with musical flair, while Petasus, De Novo, Aruba, and Taikun provide enough specialty K8s options to ensure every cluster is a unique snowflake.

Below the water – Kubernetes everywhere – Let a thousand K8s bloom

Let’s plunge deeper. Because one Kubernetes cluster is never enough, why not sprinkle them everywhere? On-premises, in the cloud, under your desk—there’s a K8s solution for all that.

Amazon EKS Anywhere – AWS container but in your own data center
Amazon ECS Anywhere – Like EKS Anywhere but ECS
Azure Arc – Hybrid cloud for masochists
Google Anthos – Hybrid cloud something something
AWS Outposts – AWS, now with hardware shipping delays
Azure Red Hat OpenShift – Azure but with a fedora
VMware Tanzu – Because VMware heard you like Kubernetes
Red Hat OpenShift – Fedoras on AWS
IBM Cloud Kubernetes Service – Kubernetes with a touch of enterprise nostalgia
Oracle Container Engine for Kubernetes (OKE) – For the brave souls trusting Oracle
Alibaba Cloud Elastic Container Service (ACK) – K8s with Chinese characteristics
DigitalOcean Kubernetes (DOKS) – K8s in the ocean, hopefully no sharks
Linode Kubernetes Engine (LKE) – Lightweight K8s for the minimalist
Vultr Kubernetes Engine (VKE) – Yet another place to run your pods
Scaleway Kapsule – French elegance meets Kubernetes
Hetzner Cloud Managed Kubernetes – German engineering for your clusters
Nutanix Karbon - Because regular Kubernetes wasn’t converged enough
Metal Stack Cloud Kubernetes - For when virtual machines are too virtual

You might also like:

Middle of the iceberg – Serverless and function containers – Now you see me, now you don’t

As we descend to the depths, we find containers with commitment issues. They appear, do their job, and disappear.

AWS Batch – Containers that only work the night shift
AWS Lambda – Lambda’s containers for when a 250 MB zip file wasn’t enough baggage.
Azure Functions – Roll your own functions in containers and hope for the best.
Google Cloud Functions – Containers pretending to be functions, but now on Google Cloud.
Alibaba Function Compute – You get the idea.

Bottom of the iceberg – Specialized and hybrid platforms – The swiss army knife of container hosting

Down here, containers run in ways that make people question your life choices. These platforms let you host containers in environments many fear to tread.

AWS Proton – Automate your deployments and run a container
Azure Virtual Machines with Docker – When you miss managing servers but love containers
IBM Cloud Code Engine – Run anything, anywhere, if you can figure it out
Alibaba Elastic Container Instance (ECI) – Containers that disappear faster than you can say “Jack Ma”

Below the iceberg – Containers on the edge of reason

In these lightless depths, you want your containers to live life on the edge—literally. Because nothing says “enterprise-ready” like running production workloads on a smart toaster.

AWS IoT Greengrass – Run AWS Lambda and Docker containers on everything from factory equipment to smart fridges. Nothing says “digital transformation” like your smart fridge running machine learning models.
Azure IoT Edge – Like Greengrass, but only when your toaster prefers Windows updates.
AWS Snowball Edge – For when ‘cloud migration’ means paying FedEx to move your containers. Yes, it’s literally a box they mail you that can run containers.
AWS Snowcone – An even smaller box that runs just enough containers to make you appreciate your data center. Perfect for when you need AWS in places where AWS doesn’t want to build a region.
BalenaCloud IoT Device Management – A platform that lets you remotely deploy and manage containers on fleets of Raspberry Pis. Because nothing says “enterprise IoT” like running your production stack on $35 computers.
Fly.io – Global Edge Container Deployment, because apparently just picking one region was too simple.
Edge Node Service (Tencent Cloud) – Edge deployment behind great firewall.
StackPath Edge Computing – More edge containers.
Koyeb – Serverless Edge containers.
Platform.sh – Multi-Cloud Edge containers.
StarlingX - Edge computing platform for when 5G and IoT buzzwords aren’t enough
ZStack Edge - Edge computing with Chinese characteristics, now at the edge of the network, too

The abyss – Where containers fear to tread

And now we reach the darkest depths. For the bravest souls who look at conventional container platforms and think, “Not edgy enough.” Here lie the most unusual ways to run containers in production.

Amazon GameLift – Run your containerized services disguised as game servers. High scores may apply.
AWS Device Farm – Deploy containers on hundreds of actual phones in AWS racks. Perfect for when “mobile-first” goes too far.
AWS AppStream 2.0 – Stream Windows to run Docker to stream containers. It’s virtualization all the way down.
Google Cloud Dataflow – Hide containerized services in pipeline steps named “daily_data_normalize_37”. Hope your SRE enjoys debugging ETL.
Google Cloud Composer – Your containerized microservice masquerades as an Airflow DAG. Because nothing says reliability like cron.
Google Colab & Jupyter Notebooks – Run containers in data_preprocessing_step.ipynb. Watch ML teams debug production.
Azure Quantum – Package quantum containers with az quantum job submit. Now, your uptime is truly uncertain.
Azure Cognitive Services in Containers – Offline AI containers that promise not to become self-aware. Terms and conditions may apply.
Azure DevTest Labs – Run containerized test environments that self-destruct like Mission Impossible tapes. Perfect for when temporary becomes permanent.

Beyond the abyss

There you have it, the container iceberg. And I didn’t even have room to add the extra cursed ways you can run containers. Here is some of what didn’t make it:

Cloud IDEs and Workspaces – Want to turn your development environment into a sneaky container platform? Take your pick: GitHub Codespaces, GitPod for the GitLab enthusiasts, or Eclipse Che for the masochists who miss Eclipse crashing locally. JetBrains Space or Replit? All this lets you run a container until you close your browser tab.
GitHub Actions et al. – Ever wanted to run a production service disguised as a CI job? Just label your production API start-up script as “integration_test_step_42”, add a sleep 21600 and a call to retrigger itself, and hope nobody notices your “test” has been running for months. Apply this same trick to AWS CodeBuild, GitLab CI/CD, CircleCI, Azure Pipelines, Travis CI, Bitbucket Pipelines, Drone CI, Jenkins Cloud, TeamCity Cloud, and Google Cloud Build for Bonus points.

Managing your container zoo with pulumi

Whether you’re deploying containers to mainstream cloud providers or attempting to run them on quantum computers (really, please let us know how that goes), Pulumi helps you manage it all with real code instead of config file soup. Our Kubernetes support means you can wrangle your containers wherever they might roam – from AWS to Azure, GCP to Kubernetes, or even that smart toaster you’re eyeing for production deployment.

With Pulumi, you get:

Cloud-native container orchestration across all major platforms and Kubernetes distributions
Infrastructure testing to ensure your containers deploy correctly (even in the weird places)
Provider templates for when you invent yet another way to run containers
Stack references for managing multiple environments without losing your mind
Automation API for programmatically herding your container fleets

Ready to bring some sanity to your container deployment strategy? Get started with Pulumi:

Try Pulumi for Free

The final word

At this point, 105 options in, you might wonder: “Has cloud container hosting gone too far?” Well, I’ve a solution to propose:

At Pulumi, we’ve got providers for all the usual suspects and, surprisingly, many more in this container circus. And if you’ve figured out how to run containers on a quantum computer inside a data pipeline in New Zealand, you can write a provider for that, too.

So, use Pulumi and we will figure out how RedHat-Tanzu-Greengrass-Icecore-Device-Farm works and provide you a sane interface to it. You’ve got other things to worry about.

Improving Pulumi’s Docker Images

Julien Poissonnier — Fri, 27 Sep 2024 00:00:00 +0000

The Pulumi Docker Containers provide a convenient way for running Pulumi in CI/CD pipelines, or for running Pulumi in environments where you don’t want to install the Pulumi CLI directly. These images also power Pulumi Deployments. We provide several flavors of images, including the pulumi/pulumi image that includes all supported language runtimes in a single image, as well as slim images for each language runtime, for example pulumi/pulumi-python or pulumi/pulumi-nodejs.

To provide more flexibility for choosing the version of the programming language to use, we have added versioned images for the language specific images covering all of our supported languages. We now also support setting the version of the Node.js and Python runtimes used in Pulumi Deployments by using .node-version and .python-version files.

.NET 6.0 has since reached end of life. The .NET 6.0 images referenced in this post are no longer available. See the current supported .NET versions.

For Python we provide images for Python 3.9 to 3.12, for Node.js we have images for Node.js 18, 20 and 22, and for .NET we have images for .NET 6.0 and 8.0. These versioned images include the language version in the image name, for example pulumi/pulumi-python-3.12 or pulumi/pulumi-nodejs-22.

The Go image is not versioned, as the Go runtime natively supports multiple versions via its Go Toolchains feature. The go statement in your Pulumi project’s go.mod file determines the Go version used to compile your program.

Updating the Default Language Versions

In November 2024 the images without a version suffix, like pulumi/pulumi-python, and the pulumi/pulumi image, will be updated to use the latest versions for each of the language runtimes by default:

Language Runtime	Current Version	New Version
.NET	6.0	8.0
Go	1.21	1.23
Node.js	18	22
Python	3.9	3.13
Java	17	21

The default versions will be updated as new versions of the language runtimes are released, matching the versions supported by the Pulumi CLI. This will enable the unversioned pulumi/pulumi image to stay evergreen as new runtimes come into and out of support.

The pulumi-provider-build-environment image, which is useful for building Pulumi providers, will also be updated with the latest language runtimes, as well as upgrading GoReleaser from v1 to v2. See the upgrade instructions on how to migrate your configuration to v2.

If you require a specific version of a language runtime, you can use the versioned images. If you want to use the latest versions of the language runtimes, you can use the images without a version suffix.

Setting the Language Version in Pulumi Deployments

When developing Node.js and Python programs, it is common to use a tool like nvm or pyenv to manage the version of the runtime used in your development environment. These tools use a .node-version or .python-version file to specify the version of the runtime to use in the current directory.

Using the latest version of the pulumi/pulumi image, Pulumi Deployments now supports these files to set the version of the Node.js and Python runtimes used in the Deployment environment. For example, to use Node.js 22 in a Deployment, you can add a .node-version file to your project with the content 22. The Deployment will then use Node.js 22 to run your Pulumi program.

The pulumi/pulumi image ships with Node.js 18, 20 and 22 pre-installed, as well as Python 3.9, 3.10, 3.11 and 3.12. Only the latest patch release of these versions is pre-installed, and it is therefore recommended you only specify the major version in the .node-version and .python-version files. If you provide a more specific version that does not match any of the pre-installed versions, it will be downloaded and installed on demand for each Deployment run.

To support more flexibility for .NET versions, the default image now also ships both .NET 6.0 and 8.0, allowing you to specify the version of .NET used in a deployment in the TargetFramework property in your project’s .csproj or .fsproj file.

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
 <TargetFramework>net8.0</TargetFramework>
 ...

If you want to use one of the language specific images, or your own custom built image, you can set a custom executor image in the Deployment settings.

Additional Tools

We recently added native Poetry support to Pulumi, and all of our images that include Python now ship with Poetry pre-installed. Images that include Node.js now ship with pnpm pre-installed.

To use Poetry set the toolchain runtime option to poetry:

name: pulumi-and-poetry-are-best-friends
runtime:
 name: python
 options:
 toolchain: poetry

To use pnpm set the packagemanager runtime option to pnpm:

name: pulumi-and-pnpm-sitting-in-a-tree
runtime:
 name: nodejs
 options:
 packagemanager: pnpm

These options work everywhere you run Pulumi, be it by directly running the Pulumi CLI locally, in CI/CD pipelines using our docker images, in GitHub Actions using the Pulumi Action, or in Pulumi Deployments.

Conclusion

These updates ensure that you get the latest version of the language runtimes by default, and provide more flexibility for choosing a specific version of the language runtime in your Pulumi projects and Deployments when required. Pulumi Deployments now also ship with Poetry and pnpm pre-installed, making it easier to use these tools in your Pulumi projects.

Introducing The New Docker Build Provider

Bryce Lampe — Thu, 25 Apr 2024 09:00:00 -0700

Deploying and managing containerized workloads is one of Pulumi’s fastest-growing areas. Standing up managed container services and Kubernetes clusters is a common area for automation, and many of our customers use Pulumi to automate building and publishing images to their registry of choice.

Given this critical use case, we are thrilled to introduce the latest addition to the Pulumi ecosystem: the new Docker Build provider, designed to streamline and modernize Docker image builds from your Pulumi programs.

This new addition expands upon the solid foundation of our highly utilized Docker provider. It elevates the docker.Image resource, one of the most heavily used and most powerful resources in the Pulumi ecosystem, into its very own dedicated package. By fully embracing the power of BuildKit, the Docker Build provider brings many new features to support the best-in-class Docker capabilities developers love.

The new provider exposes Docker’s next-gen buildx interface, so now even your most complex Docker images can be handled by Pulumi. This is a remarkably flexible and versatile tool for building images and includes key features such as,

Multi-platform image support: Build images that run seamlessly across different hardware architectures.
Advanced caching mechanisms: Speed up builds and reduce resource consumption by utilizing cache backends like S3, GitHub Actions, local disk, and more.
Support for build secrets: Unlike building images with the docker CLI, which requires juggling environment variables or files on disk, Pulumi’s first-class support for secrets means you can now safely and efficiently incorporate sensitive information into your builds. With Pulumi ESC (Environments, Secrets, and Configuration), it’s easy to share build secrets with other developers and teams.
Support for multiple export types: Export your images to registries, disk, or blob storage to increase the power and flexibility of your workflows.
Support for Docker Build Cloud: Use Docker Build Cloud to offload your builds and caches to the cloud, enhancing productivity and performance.

A brief history

Pulumi first introduced the Docker provider in 2018, and it has been widely adopted since. Over the years, Pulumi has invested in the Docker provider, notably introducing version 4.0 last year and additional improvements like build-on-preview behavior.

At the same time, the Docker build ecosystem has seen tremendous advancements in how images can be built and distributed. These changes were initially experimental, but they became official when BuildKit graduated to become the default builder in Docker version 23.

We have heard many requests from users to expose more BuildKit functionality in the Docker provider. After some consideration, we decided that a new, standalone provider focused exclusively on building images would provide the best overall user experience. In addition, it allows Pulumi to stay current with the evolving Docker build landscape.

Getting started

Add the docker-build package to your Pulumi program to take full advantage of modern image builds.

import * as docker_build from "@pulumi/docker-build";

import pulumi_docker_build as docker_build

using DockerBuild = Pulumi.DockerBuild;

import "github.com/pulumi/pulumi-docker-build/sdk/go/dockerbuild"

resources:
 my-image:
 type: docker-build:Image

import com.pulumi.dockerbuild.Image

Suppose your Pulumi program has a subfolder called ./app that contains a file named Dockerfile (its contents can be as simple as FROM alpine). In that case, the example below shows:

how to build a multi-platform image (linux/amd64 and linux/arm64),
publish the image to a remote AWS ECR registry, and;
use an inline cache to speed up subsequent builds.

import * as pulumi from "@pulumi/pulumi"
import * as aws from "@pulumi/aws";
import * as docker_build from "@pulumi/docker-build";

// Create an ECR repository for pushing.
const ecrRepository = new aws.ecr.Repository("ecr-repository", {});

// Grab auth credentials for ECR.
const authToken = aws.ecr.getAuthorizationTokenOutput({
 registryId: ecrRepository.registryId,
});

// Build and push an image to ECR with inline caching.
const myImage = new docker_build.Image("my-image", {
 // Tag our image with our ECR repository's address.
 tags: [pulumi.interpolate`${ecrRepository.repositoryUrl}:latest`],
 context: {
 location: "./app",
 },
 // Use the pushed image as a cache source.
 cacheFrom: [{
 registry: {
 ref: pulumi.interpolate`${ecrRepository.repositoryUrl}:latest`,
 },
 }],
 // Include an inline cache with our pushed image.
 cacheTo: [{
 inline: {},
 }],
 // Build a multi-platform image manifest for ARM and AMD.
 platforms: [
 "linux/amd64",
 "linux/arm64",
 ],
 // Push the final result to ECR.
 push: true,
 // Provide our ECR credentials.
 registries: [{
 address: ecrRepository.repositoryUrl,
 password: authToken.password,
 username: authToken.userName,
 }],
});

// Export a ref for the pushed images so we can deploy it.
export const ref = myImage.ref;

import pulumi
import pulumi_aws as aws
import pulumi_docker_build as docker_build

# Create an ECR repository for pushing.
ecr_repository = aws.ecr.Repository("ecr-repository")

# Grab auth credentials for ECR.
auth_token = aws.ecr.get_authorization_token_output(registry_id=ecr_repository.registry_id)

# Build and push an image to ECR with inline caching.
my_image = docker_build.Image("my-image",
 # Tag our image with our ECR repository's address.
 tags=[ecr_repository.repository_url.apply(lambda repository_url: f"{repository_url}:latest")],
 context=docker_build.BuildContextArgs(
 location="./app",
 ),
 # Use the pushed image as a cache source.
 cache_from=[docker_build.CacheFromArgs(
 registry=docker_build.CacheFromRegistryArgs(
 ref=ecr_repository.repository_url.apply(lambda repository_url: f"{repository_url}:latest"),
 ),
 )],
 # Include an inline cache with our pushed image.
 cache_to=[docker_build.CacheToArgs(
 inline=docker_build.CacheToInlineArgs(),
 )],
 # Build a multi-platform image manifest for ARM and AMD.
 platforms=[
 docker_build.Platform.LINUX_AMD64,
 docker_build.Platform.LINUX_ARM64,
 ],
 # Push the final result to ECR.
 push=True,
 # Provide our ECR credentials.
 registries=[docker_build.RegistryArgs(
 address=ecr_repository.repository_url,
 password=auth_token.password,
 username=auth_token.user_name,
 )],
)

# Export a ref for the pushed images so we can deploy it.
pulumi.export("ref", my_image.ref)

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;
using DockerBuild = Pulumi.DockerBuild;

return await Deployment.RunAsync(() =>
{
 // Create an ECR repository for pushing.
 var ecrRepository = new Aws.Ecr.Repository("ecr-repository");

 // Grab auth credentials for ECR.
 var authToken = Aws.Ecr.GetAuthorizationToken.Invoke(new()
 {
 RegistryId = ecrRepository.RegistryId,
 });

 // Build and push an image to ECR with inline caching.
 var myImage = new DockerBuild.Image("my-image", new()
 {
 // Tag our image with our ECR repository's address.
 Tags = new[]
 {
 ecrRepository.RepositoryUrl.Apply(repositoryUrl => $"{repositoryUrl}:latest"),
 },
 Context = new DockerBuild.Inputs.BuildContextArgs
 {
 Location = "./app",
 },
 // Use the pushed image as a cache source.
 CacheFrom = new[]
 {
 new DockerBuild.Inputs.CacheFromArgs
 {
 Registry = new DockerBuild.Inputs.CacheFromRegistryArgs
 {
 Ref = ecrRepository.RepositoryUrl.Apply(repositoryUrl => $"{repositoryUrl}:latest"),
 },
 },
 },
 // Include an inline cache with our pushed image.
 CacheTo = new[]
 {
 new DockerBuild.Inputs.CacheToArgs
 {
 Inline = null,
 },
 },
 // Build a multi-platform image manifest for ARM and AMD.
 Platforms = new[]
 {
 DockerBuild.Platform.Linux_amd64,
 DockerBuild.Platform.Linux_arm64,
 },
 // Push the final result to ECR.
 Push = true,
 // Provide our ECR credentials.
 Registries = new[]
 {
 new DockerBuild.Inputs.RegistryArgs
 {
 Address = ecrRepository.RepositoryUrl,
 Password = authToken.Apply(getAuthorizationTokenResult => getAuthorizationTokenResult.Password),
 Username = authToken.Apply(getAuthorizationTokenResult => getAuthorizationTokenResult.UserName),
 },
 },
 });

 // Export a ref for the pushed images so we can deploy it.
 return new Dictionary<string, object?>
 {
 ["ref"] = myImage.Ref,
 };
});

package main

import (
 "fmt"

 "github.com/pulumi/pulumi-aws/sdk/v6/go/aws/ecr"
 "github.com/pulumi/pulumi-docker-build/sdk/go/dockerbuild"
 "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 // Create an ECR repository for pushing.
 ecrRepository, err := ecr.NewRepository(ctx, "ecr-repository", nil)
 if err != nil {
 return err
 }

 // Grab auth credentials for ECR.
 authToken := ecr.GetAuthorizationTokenOutput(ctx, ecr.GetAuthorizationTokenOutputArgs{
 RegistryId: ecrRepository.RegistryId,
 }, nil)

 // Build and push an image to ECR with inline caching.
 myImage, err := dockerbuild.NewImage(ctx, "my-image", &dockerbuild.ImageArgs{
 // Tag our image with our ECR repository's address.
 Tags: pulumi.StringArray{
 ecrRepository.RepositoryUrl.ApplyT(func(repositoryUrl string) (string, error) {
 return fmt.Sprintf("%v:latest", repositoryUrl), nil
 }).(pulumi.StringOutput),
 },
 Context: &dockerbuild.BuildContextArgs{
 Location: pulumi.String("./app"),
 },
 // Use the pushed image as a cache source.
 CacheFrom: dockerbuild.CacheFromArray{
 &dockerbuild.CacheFromArgs{
 Registry: &dockerbuild.CacheFromRegistryArgs{
 Ref: ecrRepository.RepositoryUrl.ApplyT(func(repositoryUrl string) (string, error) {
 return fmt.Sprintf("%v:latest", repositoryUrl), nil
 }).(pulumi.StringOutput),
 },
 },
 },
 // Include an inline cache with our pushed image.
 CacheTo: dockerbuild.CacheToArray{
 &dockerbuild.CacheToArgs{
 Inline: nil,
 },
 },
 // Build a multi-platform image manifest for ARM and AMD.
 Platforms: dockerbuild.PlatformArray{
 dockerbuild.Platform_Linux_amd64,
 dockerbuild.Platform_Linux_arm64,
 },
 // Push the final result to ECR.
 Push: pulumi.Bool(true),
 // Provide our ECR credentials.
 Registries: dockerbuild.RegistryArray{
 &dockerbuild.RegistryArgs{
 Address: ecrRepository.RepositoryUrl,
 Password: authToken.ApplyT(func(authToken ecr.GetAuthorizationTokenResult) (*string, error) {
 return &authToken.Password, nil
 }).(pulumi.StringPtrOutput),
 Username: authToken.ApplyT(func(authToken ecr.GetAuthorizationTokenResult) (*string, error) {
 return &authToken.UserName, nil
 }).(pulumi.StringPtrOutput),
 },
 },
 })
 if err != nil {
 return err
 }

 // Export a ref for the pushed images so we can deploy it.
 ctx.Export("ref", myImage.Ref)
 return nil
 })
}

description: Push to AWS ECR with caching
name: ecr
outputs:
 ref: ${my-image.ref}
resources:
 # Create an ECR repository for pushing.
 ecr-repository:
 type: aws:ecr:Repository

 # Build and push an image to ECR with inline caching.
 my-image:
 type: docker-build:Image
 properties:
 # Tag our image with our ECR repository's address.
 tags:
 - ${ecr-repository.repositoryUrl}:latest
 context:
 location: ./app
 # Use the pushed image as a cache source.
 cacheFrom:
 - registry:
 ref: ${ecr-repository.repositoryUrl}:latest
 # Include an inline cache with our pushed image.
 cacheTo:
 - inline: {}
 # Build a multi-platform image manifest for ARM and AMD.
 platforms:
 - linux/amd64
 - linux/arm64
 # Push the final result to ECR.
 push: true
 # Provide our ECR credentials.
 registries:
 - address: ${ecr-repository.repositoryUrl}
 password: ${auth-token.password}
 username: ${auth-token.userName}

runtime: yaml
variables:
 auth-token:
 # Grab auth credentials for ECR.
 fn::aws:ecr:getAuthorizationToken:
 registryId: ${ecr-repository.registryId}

package myapp;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.ecr.Repository;
import com.pulumi.aws.ecr.EcrFunctions;
import com.pulumi.aws.ecr.inputs.GetAuthorizationTokenArgs;
import com.pulumi.dockerbuild.Image;
import com.pulumi.dockerbuild.ImageArgs;
import com.pulumi.dockerbuild.inputs.CacheFromArgs;
import com.pulumi.dockerbuild.inputs.CacheFromRegistryArgs;
import com.pulumi.dockerbuild.inputs.CacheToArgs;
import com.pulumi.dockerbuild.inputs.CacheToInlineArgs;
import com.pulumi.dockerbuild.inputs.BuildContextArgs;
import com.pulumi.dockerbuild.inputs.RegistryArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
 public static void main(String[] args) {
 Pulumi.run(App::stack);
 }

 public static void stack(Context ctx) {
 // Create an ECR repository for pushing.
 var ecrRepository = new Repository("ecrRepository");

 // Grab auth credentials for ECR.
 final var authToken = EcrFunctions.getAuthorizationToken(GetAuthorizationTokenArgs.builder()
 .registryId(ecrRepository.registryId())
 .build());

 // Build and push an image to ECR with inline caching.
 var myImage = new Image("myImage", ImageArgs.builder()
 // Tag our image with our ECR repository's address.
 .tags(ecrRepository.repositoryUrl().applyValue(repositoryUrl -> String.format("%s:latest", repositoryUrl)))
 .context(BuildContextArgs.builder()
 .location("./app")
 .build())
 // Use the pushed image as a cache source.
 .cacheFrom(CacheFromArgs.builder()
 .registry(CacheFromRegistryArgs.builder()
 .ref(ecrRepository.repositoryUrl().applyValue(repositoryUrl -> String.format("%s:latest", repositoryUrl)))
 .build())
 .build())
 // Include an inline cache with our pushed image.
 .cacheTo(CacheToArgs.builder()
 .inline()
 .build())
 // Build a multi-platform image manifest for ARM and AMD.
 .platforms(
 "linux/amd64",
 "linux/arm64")
 // Push the final result to ECR.
 .push(true)
 // Provide our ECR credentials.
 .registries(RegistryArgs.builder()
 .address(ecrRepository.repositoryUrl())
 .password(authToken.applyValue(getAuthorizationTokenResult -> getAuthorizationTokenResult).applyValue(authToken -> authToken.applyValue(getAuthorizationTokenResult -> getAuthorizationTokenResult.password())))
 .username(authToken.applyValue(getAuthorizationTokenResult -> getAuthorizationTokenResult).applyValue(authToken -> authToken.applyValue(getAuthorizationTokenResult -> getAuthorizationTokenResult.userName())))
 .build())
 .build());

 ctx.export("ref", myImage.ref());
 }
}

The Pulumi output, ref, provides a convenient way to reference the pushed image in downstream Pulumi resources like ECS TaskDefinitions or Kubernetes Deployments.

Build container images with Pulumi

Use the Docker Build provider to build multi-platform images, cache layers across builds, and push to your registry of choice as part of your Pulumi program.

Get started

Migrating from docker.Image to docker_build.Image

The new docker_build.Image replaces the old docker.Image resource. It adds new features and addresses many bugs with the previous resource by fully aligning with Docker’s underlying buildx commands. From now on, we will continue to invest in Docker Build and the docker_build.Image resource.

We do not expect to make further changes to docker.Image. It will remain available for the foreseeable future, so you can continue using it if it meets your needs. However, we recommend you migrate your images to docker_build.Image to get the best possible support, features, and performance. We expect to deprecate the docker.Image resource in the future.

The migration process is straightforward and detailed in the API documentation. Docker Build provides a superset functionality over the previous docker.Image resource; thus, you can migrate existing resources without issue. The new Docker Build Image options will look very familiar if you use the Docker command-line tool.

The new Docker Build provider matches the Docker CLI behavior. Thus, it does not push images by default. If you want to push to a registry, include push: true in the code just as you would include --push on the command line.

The new Docker Build provider builds images by default during previews to reduce the risk of merging broken images as part of CI pipelines. You can change the default behavior by specifying a buildOnPreview flag.

Jump over to the applicable migration guide to learn how to update your existing Pulumi program:

Migrating from Docker provider v3
Migrating from Docker provider v4

Migrating from Docker provider v3

Version 3.x of the Docker provider is still widely used because it exposes BuildKit functionality through raw command-line arguments. However, the new Docker Build provider exposes those arguments as top-level fields on the resource.

Reference the below TypeScript code to compare a v3 definition of a docker.Image with the new dockerbuild.Image. In particular, note the extraOptions in v3 are now top-level fields, e.g., cacheFrom, cacheTo, platforms, etc.

// v3 Image
const v3 = new docker.Image("v3-image", {
 imageName: "myregistry.com/user/repo:latest",
 localImageName: "local-tag",
 skipPush: false,
 build: {
 dockerfile: "./Dockerfile",
 context: "../app",
 target: "mytarget",
 args: {
 MY_BUILD_ARG: "foo",
 },
 env: {
 DOCKER_BUILDKIT: "1",
 },
 extraOptions: [
 "--cache-from",
 "type=registry,myregistry.com/user/repo:cache",
 "--cache-to",
 "type=registry,myregistry.com/user/repo:cache",
 "--add-host",
 "metadata.google.internal:169.254.169.254",
 "--secret",
 "id=mysecret,src=https://www.pulumi.com/local/secret",
 "--ssh",
 "default=/home/runner/.ssh/id_ed25519",
 "--network",
 "host",
 "--platform",
 "linux/amd64",
 ],
 },
 registry: {
 server: "myregistry.com",
 username: "username",
 password: pulumi.secret("password"),
 },
});

// v3 Image after migrating to docker-build.Image
const v3Migrated = new dockerbuild.Image("v3-to-buildx", {
 tags: ["myregistry.com/user/repo:latest", "local-tag"],
 push: true,
 dockerfile: {
 location: "./Dockerfile",
 },
 context: {
 location: "../app",
 },
 target: "mytarget",
 buildArgs: {
 MY_BUILD_ARG: "foo",
 },
 cacheFrom: [{ registry: { ref: "myregistry.com/user/repo:cache" } }],
 cacheTo: [{ registry: { ref: "myregistry.com/user/repo:cache" } }],
 secrets: {
 mysecret: "value",
 },
 addHosts: ["metadata.google.internal:169.254.169.254"],
 ssh: {
 default: ["/home/runner/.ssh/id_ed25519"],
 },
 network: "host",
 platforms: ["linux/amd64"],
 registries: [{
 address: "myregistry.com",
 username: "username",
 password: pulumi.secret("password"),
 }],
});

Migrating from Docker provider v4

The new Docker Build provider largely exposes the same fields as v4, but the fields are pluralized or renamed to better align with the Docker CLI.

Reference the below TypeScript code to compare a v4 definition of a docker.Image with the new dockerbuild.Image. In particular, note the top-level, pluralized names, e.g., registries, platforms, etc.

// v4 Image
const v4 = new docker.Image("v4-image", {
 imageName: "myregistry.com/user/repo:latest",
 skipPush: false,
 build: {
 dockerfile: "./Dockerfile",
 context: "../app",
 target: "mytarget",
 args: {
 MY_BUILD_ARG: "foo",
 },
 cacheFrom: {
 images: ["myregistry.com/user/repo:cache"],
 },
 addHosts: ["metadata.google.internal:169.254.169.254"],
 network: "host",
 platform: "linux/amd64",
 },
 buildOnPreview: true,
 registry: {
 server: "myregistry.com",
 username: "username",
 password: pulumi.secret("password"),
 },
});

// v4 Image after migrating to docker-build.Image
const v4Migrated = new dockerbuild.Image("v4-to-buildx", {
 tags: ["myregistry.com/user/repo:latest"],
 push: true,
 dockerfile: {
 location: "./Dockerfile",
 },
 context: {
 location: "../app",
 },
 target: "mytarget",
 buildArgs: {
 MY_BUILD_ARG: "foo",
 },
 cacheFrom: [{ registry: { ref: "myregistry.com/user/repo:cache" } }],
 cacheTo: [{ registry: { ref: "myregistry.com/user/repo:cache" } }],
 addHosts: ["metadata.google.internal:169.254.169.254"],
 network: "host",
 platforms: ["linux/amd64"],
 registries: [{
 address: "myregistry.com",
 username: "username",
 password: pulumi.secret("password"),
 }],
});

Conclusion

Launching the new Docker Build provider marks a significant milestone in modernizing container management for developers. The new package, which contains the docker_build.Image resource reflects our commitment to innovation and user-centric development. By incorporating the latest BuildKit technology, the Docker Build provider supports the newest features, enhances multi-architecture builds, and improves caching strategies. Moreover, its integration with Docker Build Cloud underscores our dedication to providing a cutting-edge toolset for developers. This launch is a testament to our ongoing efforts to modernize and improve how developers build images.

Check out the Pulumi Docker Build documentation for more details on utilizing the Docker Build provider.

If you are still wondering, “Which provider should I use?” the answer depends on whether you are doing anything related to docker build.

Provider	Use cases
`@pulumi/docker-build`	Use this provider to build and push Docker images. Ideal for scenarios requiring automation of image creation with Docker, including setting up CI/CD pipelines for Docker image generation.
`@pulumi/docker`	Use this provider for everything else, including managing local Docker containers, networks, and volumes on the host machine.

Local Testing With Pulumi

Aaron Kao — Fri, 28 Apr 2023 00:00:00 +0000

If you’ve been following along with our IaC Recommended Practices series, then you’re already familiar with Zephyr Archaeotech Emporium, the fictional company at the center of the series. Today, you’ll get an inside look at how Zephyr starts using Pulumi for locally testing the application code for their online store and accelerating the inner dev loop for their development team.

In the event you’re not familiar with the term “inner dev loop,” it’s used to describe the iterative code/build/test loop that every developer goes through to write code and verify that it works before they push their code to version control to be reviewed and merged. Speeding up the inner dev loop makes it possible for developers to iterate on their code more quickly, reducing the time spent waiting on tools or environments.

Structured as a conversation between two employees at Zephyr—Alice, a developer on the team for Zephyr’s online store application, and Bob, a member of Zephyr’s platform engineering team—this post shows one way to use Pulumi to help accelerate the inner dev loop. Let’s listen in…

Listening in at Zephyr HQ

In a conversation at Zephyr HQ between Bob and Alice one day, Bob commented, “I’m really enjoying Pulumi. It’s nice for the platform team to be able to use TypeScript to define all the infrastructure we need.”

“Or to deploy our application onto that infrastructure,” Alice responded. “I just wish there was a way to speed up testing changes to our code.”

“Do you mean testing the Pulumi code?”

“No, no, I was talking about our application code—the code for the online store.”

“Oh, what’s wrong with the current way it’s handled? Is there something we can do better?”

Alice paused. “Well, don’t get me wrong, the way we use per-developer stacks makes it super easy for me to deploy an entire copy of our environment. The problem is that…well, it takes a fair amount of time to create all the AWS stuff. Sometimes I just need something faster, just to test some quick changes to the code before deploying the app to my dev stack.”

Bob nodded thoughtfully. “I see. You know, Pulumi has a Docker provider; in fact, they recently released a new version of their Docker provider.”

Alice’s eyes lit up. “So, you mean I can automate my local Docker instance using Pulumi?”

“Yeah, why?”

Alice smiled. “I have an idea.”

Using Pulumi for the inner dev loop

A couple days later, Alice contacted Bob and said, “I want to show you what I’ve come up with.”

To see the code that Alice created for local testing of the Zephyr online store with Pulumi, visit the zephyr-app repository and look at the blog/inner-dev-loop branch.

When Bob met up with Alice, Alice showed him a TypeScript program she’d written with Pulumi’s Docker provider that automates building and deploying the Zephyr online store to a local Docker daemon.

“With this code,” Alice explains, “I can just run pulumi up and it will deploy the entire Zephyr online store locally, all in just a few minutes. Here, let me just run pulumi up real quick.”

“But why use this instead of Docker Compose?”

“Oh, there’s absolutely nothing wrong with Docker Compose; it’s a great tool!” Alice replied. “But this allows me to work with TypeScript, and to build logic into my Pulumi program. Like this feature here—I can specify whether I want to build a container, or use the released version of a container.”

“See, at the top I have the Pulumi program check for a configuration value that I set using pulumi config set. If the value isn’t set, it defaults to build.”

// Get configuration values
const config = new pulumi.Config();
const srcRepoPath = config.get("srcRepoPath") || "../..";
const assetsFlag = config.get("assetsFlag") || "build";
const cartsFlag = config.get("cartsFlag") || "build";
const catalogFlag = config.get("catalogFlag") || "build";
const checkoutFlag = config.get("checkoutFlag") || "build";
const ordersFlag = config.get("ordersFlag") || "build";

“There’s one for each service in the online store?” Bob asked.

“Right, except for the UI service, which is always built. This is so I can independently test changes to only a specific service. Farther down, the Pulumi code checks for this value and then either builds the container—pulling in whatever changes I’ve made—or uses an already released version of the container.”

// Build the assets image or pull remote image, depending on value of assetsFlag
var assetsImageRef: pulumi.Input<string>;
if (assetsFlag == "build") {
 const assetsImage = new docker.Image("assets-image", {
 build: {
 context: `${srcRepoPath}/src/assets`,
 dockerfile: `${srcRepoPath}/src/assets/Dockerfile`,
 platform: imagePlatform,
 },
 imageName: "zephyr-assets:latest",
 skipPush: true,
 }, { retainOnDelete: true });
 assetsImageRef = assetsImage.id;
} else {
 const assetsRegistryImage = docker.getRegistryImage({
 name: "public.ecr.aws/aws-containers/retail-store-sample-assets:0.2.0",
 });
 const assetsRemoteImage = new docker.RemoteImage("assets-image", {
 name: assetsRegistryImage.then(assetsRegistryImage => assetsRegistryImage.name),
 pullTriggers: [assetsRegistryImage.then(assetsRegistryImage => assetsRegistryImage.sha256Digest)],
 }, { retainOnDelete: true });
 assetsImageRef = assetsRemoteImage.repoDigest;
};

You can see that the released container image is hard-coded in this example. You could also pass this in as a configuration value to allow the Pulumi program to more easily account for new releases.

“By setting the flag for the assets service to build and all the other services to something else—the code only builds if the value is set to build—then I can isolate changes made to that service for testing, to be sure I haven’t broken something elsewhere.”

“That seems useful.”

“Indeed! And you can see here that we are building a Docker network for these containers; this is what enables connectivity between the various parts of the online store when it’s running locally via Docker.”

// Create a network
const network = new docker.Network("network", {
 name: "zephyr-net",
});

// Create an assets container
const assetsContainer = new docker.Container("assets-container", {
 capabilities: {
 drops: ["ALL"],
 },
 envs: [
 "PORT=8080",
 ],
 hostname: "assets",
 image: assetsImageRef,
 memory: 64,
 name: "assets",
 networksAdvanced: [
 {
 name: network.name,
 },
 ],
 restart: "always",
});

Bob nodded. “Yep, this all makes sense. Interesting, I hadn’t really considered Pulumi for this particular use case. Usually when folks mention Pulumi the first thought in my head is provisioning cloud infrastructure.”

“Oh, certainly, and it works really well for that—but it also works really well for this case, too.”

“And since we are already using Pulumi for deploying to Kubernetes in test and production, then this brings some consistency across environments. It’s just a pulumi up regardless of whether you’re running the app locally or publishing to a Kubernetes cluster in your per-developer stack, the test stack, or even the prod stack.”

“Exactly. Oh, look here. It’s done. Looks like it took just over two minutes, and now our online store app is available at this URL on localhost.”

“That’s pretty fast.”

Alice nodded. “Yeah, a lot faster than waiting on a Kubernetes cluster to provision. We still need to run this in our dev stacks to be sure that it runs in an environment that closely mirrors production, but for quick feedback on changes I make this is very useful for me as a developer.”

“So if you make a change to the code and want to see the results, what’s that look like?”

“Here, let’s do it real quick.” Alice switches to her code editor, makes a few changes, and then flips back to the terminal. “I’ll run a pulumi preview so you can see what it’s going to do.”

Alice pointed to the terminal output. “Here, Pulumi has recognized that the source code for this container has changed, and so it is replacing the container image, and restarting all the containers. Let me run pulumi up.”

Bob watches as the operation completes in about 17 seconds.

“Wow, that’s really fast!”

“Exactly, Bob. That’s what makes using Pulumi for this use case so helpful. While it doesn’t eliminate the need for our per-developer stacks, it gives developers a way to quickly see changes we’re making to the source code in very little time. When we are satisfied that the changes are working as we expect, then we can deploy to our dev stack to be sure that the changes are ready to work their way to production.”

Speed up your inner dev loop

Use Pulumi and the Docker provider to build and deploy your application locally, then promote the same program to your cloud stacks. Get started in Pulumi Cloud.

Get started

Try this out yourself

Now that you’ve seen how Alice uses Pulumi to streamline testing the Zephyr online store’s application code locally, feel free to try this out yourself! The code that you saw in this blog post is available in the zephyr-app repository on GitHub. Just select the blog/inner-dev-loop branch and go to the develop/pulumi folder.

Fast Docker Image Builds with Pulumi

Monica Rodriguez — Wed, 08 Mar 2023 14:00:00 -0800

How do I speed up Docker image builds with Pulumi? Use BuildKit (the default since Docker 23), enable a registry or layer cache so repeated builds reuse work, write a multi-stage Dockerfile so production images skip build-time dependencies, and reach for the dedicated Docker Build provider when you need buildx features like multi-platform images, build secrets, or Docker Build Cloud. With these techniques together, repeat builds in a Pulumi program commonly drop from minutes to seconds.

TL;DR

BuildKit is the default in current Docker releases and in the Pulumi Docker providers — you generally do not need to opt in.
Cache your layers somewhere persistent. A registry cache (cacheFrom / cacheTo) is what makes CI builds fast across runners and contributors.
Multi-stage Dockerfiles are the single biggest win for image size and rebuild speed when you have a compile or bundle step.
Use pulumi/docker-build for new projects. It exposes the full buildx surface (multi-platform, secrets, multiple cache backends, Docker Build Cloud).
Use pulumi/docker v4+ if you already depend on it — its docker.Image resource also rebuilds only on context change and supports BuildKit and registry caching.

What actually moves the needle

The numbers below are representative of what teams report from a typical Node.js or Python web app (single Dockerfile, ~300 MB final image). Your mileage varies with project size, network, and runner specs — treat this as a directional comparison, not a benchmark suite.

Configuration	Cold build	Repeat build (no source change)	Repeat build (small source change)
Legacy builder, no caching	minutes	minutes	minutes
BuildKit, local layer cache only	minutes	seconds (cache hit)	tens of seconds
BuildKit + multi-stage Dockerfile	minutes	seconds (cache hit)	tens of seconds
BuildKit + multi-stage + registry cache (`cacheFrom`/`cacheTo`)	minutes (first run)	seconds (cache hit)	seconds–tens of seconds, even on a fresh CI runner
`docker-build` provider with buildx + Docker Build Cloud	under 2 min	seconds (cache hit)	seconds

The headline pattern: each row past the first is dominated by what the build can skip, not by raw CPU. Pulumi’s job is to wire those caches up declaratively so they keep working across every pulumi up.

How does Pulumi build Docker images?

Pulumi has two providers for image builds, and which one you should use depends on how new your project is.

The Docker provider (pulumi/docker) is the original. Its docker.Image resource can build a local context and push to any registry as part of a Pulumi deployment, alongside resources for containers, networks, and volumes. Since v4 it rebuilds only when the build context changes and uses BuildKit by default.
The Docker Build provider (pulumi/docker-build) is a newer, dedicated provider focused exclusively on image builds. It exposes Docker’s buildx interface, so you get multi-platform builds, multiple cache backends, build secrets, and Docker Build Cloud as first-class features.

For new projects, prefer docker-build. For existing programs that already use docker.Image, you do not have to migrate — docker.Image continues to receive the speed and caching improvements covered below.

Why are my Docker builds slow?

Three things make Docker builds slow in practice, and Pulumi addresses each one declaratively.

No cache, or the wrong cache. A fresh CI runner has no local Docker layers. Without a remote cache, every build reinstalls every dependency.
Cache busting on noise. If your Dockerfile copies package.json and the rest of your source in the same step, every source change invalidates the dependency-install layer. Order layers from least-changing to most-changing.
Building dev tooling into the production image. Compilers, linters, and test frameworks have no business in a runtime image. Multi-stage builds let you discard them.

How do I enable BuildKit and registry caching in Pulumi?

BuildKit has been the default builder since Docker 23 and is the default in both Pulumi providers. The piece you usually have to configure is where the cache lives — local disk on a developer laptop is fine, but for CI you almost always want a registry cache so layers persist across runners.

With the Docker Build provider (recommended)

import * as docker_build from "@pulumi/docker-build";

const image = new docker_build.Image("my-image", {
 tags: ["docker.io/pulumibot/demo-image:latest"],
 context: { location: "./app" },
 dockerfile: { location: "./app/Dockerfile" },
 platforms: [
 "linux/amd64",
 "linux/arm64",
 ],
 cacheFrom: [{ registry: { ref: "docker.io/pulumibot/demo-image:cache" } }],
 cacheTo: [{ registry: { ref: "docker.io/pulumibot/demo-image:cache", mode: "max" } }],
 push: true,
});

cacheFrom and cacheTo together are the important pair: the first run populates the cache, every later run on any machine pulls it. mode: "max" exports cache for every layer, not just the final ones.

With the Docker provider (`docker.Image`)

import * as docker from "@pulumi/docker";

const image = new docker.Image("my-image", {
 imageName: "docker.io/pulumibot/demo-image:latest",
 build: {
 context: "app",
 dockerfile: "Dockerfile",
 platform: "linux/amd64",
 cacheFrom: {
 images: ["docker.io/pulumibot/demo-image:cache-base"],
 },
 },
});

The docker.Image resource accepts a list of cache images via cacheFrom.images. Tag a previous build with a stable cache tag (for example, :cache-base) and reference it here so subsequent builds reuse its layers.

How do I write a Dockerfile that builds fast?

The Dockerfile matters at least as much as the Pulumi code wrapping it. Two patterns do most of the work.

Order layers least-volatile first. Copy lockfiles and run dependency installs before copying source code. That way changing a .ts file does not bust the npm ci layer.

# Dependencies — only invalidates when lockfiles change
COPY package.json package-lock.json ./
RUN npm ci

# Source — changes constantly, but the dependency layer above survives
COPY . .
RUN npm run build

Use multi-stage builds to drop tooling. Compile in a fat image, copy the artifact into a slim one. The runtime image stays small and the build stage gets cached independently.

FROM node:20 AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-slim AS runtime
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
CMD ["node", "dist/server.js"]

When you combine multi-stage with a registry cache (cacheTo mode max), CI runs on fresh machines reuse both stages — the row in the table above where small source changes finish in 10–30 seconds.

How do I build multi-platform images with Pulumi?

Use the docker-build provider and pass a list to platforms. BuildKit will build all variants in parallel and push a manifest list, so a single tag serves whatever architecture the puller needs.

const image = new docker_build.Image("api", {
 tags: ["ghcr.io/example/api:latest"],
 context: { location: "./api" },
 platforms: [
 "linux/amd64",
 "linux/arm64",
 ],
 push: true,
});

If you are still on docker.Image, the build.platform field accepts a single target (for example, "linux/amd64"); for true multi-arch manifests, prefer docker-build.

How do I see Docker build output in Pulumi?

Filtered Docker build and push logs render directly in pulumi up output for both providers, so you can debug a failing layer without leaving your Pulumi run. With the Docker Build provider, structured progress shows per-stage timing — useful when you are trying to figure out which layer is the slow one.

How do I migrate an older `docker.Image` program?

If you are upgrading from a pre-v4 program, pulumi-docker v4 reshaped the docker.Image resource and renamed several supporting types, but does not manage backend state, so updating the package version and adjusting types is generally enough. The full migration guide lives in the v4.0.0 release notes.

If you are starting fresh or want the full BuildKit feature set, install pulumi-docker-build instead and follow the Docker Build provider getting started guide.

Getting started

Docker Build provider — recommended for new projects.
Docker provider — the original, including docker.Image, containers, and networks.
Introducing the Docker Build provider — deeper dive on buildx, secrets, and Docker Build Cloud.

The cheapest performance win in most Pulumi programs is wiring up a registry cache and a multi-stage Dockerfile. Start there, then reach for buildx features as the project grows.

Cloud Systems: Deploying to Amazon ECS

Kat Cosgrove — Tue, 28 Dec 2021 14:52:42 +0000

Cloud engineering is taking over software development. In a lot of ways, this is great; it allows us to build and deploy more complicated applications with less difficulty, and maintaining those applications becomes less troublesome too. We can release smaller updates more quickly than ever, ensuring that we can stay on top of feature requests and security issues. That said, the rise of cloud engineering has also introduced a lot of complexity in the form of dozens of services even within just one cloud provider. Figuring out where to start can be tough, so let’s take a practical tour! In this series, I’ll walk you through building a personal website and deploying it using modern cloud engineering practices.

Elastic Container Service

In the previous tutorial, we extended our personal website to use the Flask web framework, add server-side routing, and package everything up into a Docker container. It’s still only running locally, though, and we want to deploy it. To do that, today we’ll be learning to use Pulumi to deploy to Amazon’s Elastic Container Service. If you completed part two of this series, we’ll be picking up right where we left off. If you’re just now joining me, you can get the completed code by forking and cloning this repository.

Prerequisites:

Configuring Amazon ECS

Amazon’s ECS (Elastic Container Service) is a tool used for container orchestration. It allows you to deploy containerized applications into a cluster, defined as tasks. We’re going to use Pulumi to define all of the necessary rules and settings to do this in a secure manner, then create our infrastructure and deploy the containerized website.

First, run pulumi new python -y to start a new Pulumi project if you don’t already have one for this tutorial. From now on, we’ll be working within __main__.py

import json
import base64
import pulumi
import pulumi_aws as aws
import pulumi_docker as docker

First, we have our imports. We’re working with both AWS and Docker, so we need both of those Pulumi providers. Launch the virtual environment set up for you by Pulumi with source venv/bin/activate and run pip3 install pulumi-aws pulumi-docker to get both. If you want to make sure your dependencies are saved for later, you can run pip3 freeze > requirements.txt .

app_cluster = aws.ecs.Cluster("app-cluster")

app_vpc = aws.ec2.Vpc("app-vpc",
 cidr_block="172.31.0.0/16",
 enable_dns_hostnames=True)

app_vpc_subnet = aws.ec2.Subnet("app-vpc-subnet",
 cidr_block="172.31.32.0/20",
 vpc_id=app_vpc.id)

In this codeblock, we’re first creating our ECS cluster and naming it app-cluster. Then create a VPC (Virtual Private Cloud), and a subnet for it. VPCs are like miniature local networks, with subnets providing the addressing within that mini network. Using a VPC means you can wire up your system as you like it without worrying about how that network setup might collide with other AWS resources, since you define how that network can connect outward. If you’ve ever used Docker networking, you’ll be familiar with the idea that an internal network is different than the external interface.

It is possible to use the default VPC here rather than defining one, but AWS networking is complex, so it’s worth knowing that it is possible to define a custom VPC.

app_gateway = aws.ec2.InternetGateway("app-gateway",
 vpc_id=app_vpc.id)

app_routetable = aws.ec2.RouteTable("app-routetable",
 routes=[
 aws.ec2.RouteTableRouteArgs(
 cidr_block="0.0.0.0/0",
 gateway_id=app_gateway.id,
 )
 ],
 vpc_id=app_vpc.id)

app_routetable_association = aws.ec2.MainRouteTableAssociation("app_routetable_association",
 route_table_id=app_routetable.id,
 vpc_id=app_vpc.id)

Next, we need a gateway and a route table. The gateway’s job is to provide a target in that route table we just created and associated with our VPC. This allows our VPC to communicate with the public internet.

app_security_group = aws.ec2.SecurityGroup("security-group",
 vpc_id=app_vpc.id,
 description="Enables HTTP access",
 ingress=[aws.ec2.SecurityGroupIngressArgs(
 protocol='tcp',
 from_port=80,
 to_port=80,
 cidr_blocks=['0.0.0.0/0'],
 )],
 egress=[aws.ec2.SecurityGroupEgressArgs(
 protocol='-1',
 from_port=0,
 to_port=0,
 cidr_blocks=['0.0.0.0/0'],
 )])

Just about everything you do in AWS requires a security group. The purpose of a security group is to control traffic, both inbound and outbound. This one enables HTTP access.

# Creating an IAM role used by Fargate to execute all our services
app_exec_role = aws.iam.Role("app-exec-role",
 assume_role_policy="""{
 "Version": "2012-10-17",
 "Statement": [
 {
 "Action": "sts:AssumeRole",
 "Principal": {
 "Service": "ecs-tasks.amazonaws.com"
 },
 "Effect": "Allow",
 "Sid": ""
 }]
 }""")

# Attaching execution permissions to the exec role
exec_policy_attachment = aws.iam.RolePolicyAttachment("app-exec-policy", role=app_exec_role.name,
 policy_arn="arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy")

# Creating an IAM role used by Fargate to manage tasks
app_task_role = aws.iam.Role("app-task-role",
 assume_role_policy="""{
 "Version": "2012-10-17",
 "Statement": [
 {
 "Action": "sts:AssumeRole",
 "Principal": {
 "Service": "ecs-tasks.amazonaws.com"
 },
 "Effect": "Allow",
 "Sid": ""
 }]
 }""")

# Attaching execution permissions to the task role
task_policy_attachment = aws.iam.RolePolicyAttachment("app-access-policy", role=app_task_role.name,
 policy_arn=aws.iam.ManagedPolicy.AMAZON_ECS_FULL_ACCESS)

We’re going to be using AWS Fargate to actually run our container. Fargate is a serverless compute platform designed for running containers without requiring you to provision and manage clusters of EC2 (Elastic Compute Cloud) instances. Since our website is containerized and very small, it’s perfect for us. Services also require IAM roles, and in this case, we need to allow Fargate to execute our services and manage our tasks, so we create new roles for both and apply execution permissions to them.

In the context of Fargate, a task is a collection of containers, and a task definition tells AWS what needs to be running all at once in order to make an application run. The task definitions will be written later onm but first we need to define policies. It’s important that these policies be created first, or the task definitions won’t create correctly later on.

# Creating storage space to upload a docker image of our app to
app_ecr_repo = aws.ecr.Repository("app-ecr-repo",
 image_tag_mutability="MUTABLE")

# Attaching an application life cycle policy to the storage
app_lifecycle_policy = aws.ecr.LifecyclePolicy("app-lifecycle-policy",
 repository=app_ecr_repo.name,
 policy="""{
 "rules": [
 {
 "rulePriority": 10,
 "description": "Remove untagged images",
 "selection": {
 "tagStatus": "untagged",
 "countType": "imageCountMoreThan",
 "countNumber": 1
 },
 "action": {
 "type": "expire"
 }
 }
 ]
 }""")

The last thing we need to do for our infrastructure before we can start deploying to it is create a repository on Amazon ECR (Elastic Container Registry) where our Docker image will live, then attach an application lifecycle policy to that repository. This makes sure that we expire and remove any untagged images in the repository, keeping things from getting clogged up.

Deploying a Dockerized Flask Application to ECS

We’re now ready to deploy our website and wire all of this up!

flask_targetgroup = aws.lb.TargetGroup("flask-targetgroup",
 port=80,
 protocol="TCP",
 target_type="ip",
 vpc_id=app_vpc.id)

flask_balancer = aws.lb.LoadBalancer("flask-balancer",
 load_balancer_type="network",
 internal=False,
 security_groups=[],
 subnets=[app_vpc_subnet.id])

flask_listener = aws.lb.Listener("flask-listener",
 load_balancer_arn=flask_balancer.arn,
 port=80,
 protocol="TCP",
 default_actions=[aws.lb.ListenerDefaultActionArgs(
 type="forward",
 target_group_arn=flask_targetgroup.arn
 )])

First, we need to make it possible for our Flask application to communicate with the internet. That requires three pieces of configuration: a target group for port 80, a load balancer to spread out incoming requests and make sure our website doesn’t get overwhelmed as easily, and a listener to forward public traffic to the defined target group. The target group is directed at the endpoint for the VPC we created earlier, defining the port as it is unknown until runtime.

def get_registry_info(rid):
 creds = aws.ecr.get_credentials(registry_id=rid)
 decoded = base64.b64decode(creds.authorization_token).decode()
 parts = decoded.split(':')
 if len(parts) != 2:
 raise Exception("Invalid credentials")
 return docker.ImageRegistry(creds.proxy_endpoint, parts[0], parts[1])

app_registry = app_ecr_repo.registry_id.apply(get_registry_info)

flask_image = docker.Image("flask-dockerimage",
 image_name=app_ecr_repo.repository_url,
 build="./website",
 skip_push=False,
 registry=app_registry
)

A small helper function is required here. It’s grabbing some of our AWS credentials, specifically an authorization token, so that we can talk to the registry. Next, we build the Docker image for our website and push it to the repository we created in Amazon ECR earlier. Remember, the Dockerfile is in ./website.

flask_task_definition = aws.ecs.TaskDefinition("flask-task-definition",
 family="frontend-task-definition-family",
 cpu="256",
 memory="512",
 network_mode="awsvpc",
 requires_compatibilities=["FARGATE"],
 execution_role_arn=app_exec_role.arn,
 task_role_arn=app_task_role.arn,
 container_definitions=pulumi.Output.all(flask_image.image_name).apply(lambda args: json.dumps([{
 "name": "flask-container",
 "image": args[0],
 "memory": 512,
 "essential": True,
 "portMappings": [{
 "containerPort": 80,
 "hostPort": 80,
 "protocol": "tcp"
 }],
 }])))

We need a task definition for the Flask instance. AWS Fargate will be managing this for us, using the roles we defined earlier. We’re also handing it a container definition, including the image name and a little bit of information about it, like the container and host ports.

flask_service = aws.ecs.Service("flask-service",
 cluster=app_cluster.arn,
 desired_count=1,
 launch_type="FARGATE",
 task_definition=flask_task_definition.arn,
 wait_for_steady_state=False,
 network_configuration=aws.ecs.ServiceNetworkConfigurationArgs(
 assign_public_ip=True,
 subnets=[app_vpc_subnet.id],
 security_groups=[app_security_group.id]
 ),
 load_balancers=[aws.ecs.ServiceLoadBalancerArgs(
 target_group_arn=flask_targetgroup.arn,
 container_name="flask-container",
 container_port=80,
 )],
 opts=pulumi.ResourceOptions(depends_on=[flask_listener]),
)

Finally, we actually launch our website. We need to create a new service definition and hand it all of the resources we created earlier, beginning with the ECS cluster itself. It has the task definition, our network configurations, and our load balancers, and we make sure that this particular piece of code isn’t executed until the listener we created to watch for traffic is online.

As a shortcut to finding our website, export the DNS name of our load balancer as an output from Pulumi as the last part of the program:

pulumi.export("app-url", flask_balancer.dns_name)

We’re ready to go! Set your AWS region in your terminal:

pulumi config set aws:region us-west-2

Then run pulumi up to watch it go! This time, we’re going to see way more services created than before.

 Type Name Status Info
 + pulumi:pulumi:Stack part-three-dev created
 + ├─ docker:image:Image flask-dockerimage created
 + ├─ aws:ec2:Vpc app-vpc created
 + ├─ aws:ecs:Cluster app-cluster created
 + ├─ aws:iam:Role app-exec-role created
 + ├─ aws:iam:Role app-task-role created
 + ├─ aws:ecr:Repository app-ecr-repo created
 + ├─ aws:iam:RolePolicyAttachment app-exec-policy created
 + ├─ aws:iam:RolePolicyAttachment app-access-policy created
 + ├─ aws:ecr:LifecyclePolicy app-lifecycle-policy created
 + ├─ aws:ec2:Subnet app-vpc-subnet created
 + ├─ aws:ec2:InternetGateway app-gateway created
 + ├─ aws:ec2:SecurityGroup security-group created
 + ├─ aws:lb:TargetGroup flask-targetgroup created
 + ├─ aws:ecs:TaskDefinition flask-task-definition created
 + ├─ aws:lb:LoadBalancer flask-balancer created
 + ├─ aws:ec2:RouteTable app-routetable created
 + ├─ aws:ec2:MainRouteTableAssociation app_routetable_association created
 + ├─ aws:lb:Listener flask-listener created
 + └─ aws:ecs:Service flask-service created

Outputs:
 app-url: "flask-balancer-a90d260-057e5a40e0267b63.elb.us-west-2.amazonaws.com"

Resources:
 + 20 created

Duration: 3m36s

Pulumi has created 20 resources for you, and helpfully returned the DNS address of your load balancer. I’ve snipped out the diagnostics section of this output for the sake of keeping things brief, but you will also see the step-by-step process Docker goes through building and running your image. Go to that URL after a couple of minutes, and your website is online!

We now have a functional, multi-page website with server-side routing, packaged up into a Docker container and deployed to a fully-configured AWS ECS cluster in just a couple hundred lines of Python, all without leaving the same repository our website is stored in. What if we want to be able to scale really large, though? Some resiliency would be nice. Stay tuned for the next blog for an introduction to Kubernetes, where we’ll learn to deploy our website to Amazon’s Elastic Kubernetes Service!

Cloud Systems: Containerizing a Website

Kat Cosgrove — Mon, 27 Dec 2021 12:26:10 -0800

In part one of this series, we built a personal website and deployed it to AWS S3. That works perfectly well for a static, single-page application with minimal interactivity, but if you want server-side routing or database interactivity, things have to get a little bit more complicated. In part two of this series, we’ll be adding a couple more pages to our personal website, adding server-side routing, and containerizing it with Docker.

Containers

So, what’s a container and why would you want to use one? You can think of a container here the exact same way you think of containers on a shipping barge. On that barge is a bunch of shipping containers, and inside each shipping container is a bunch of packages. The barge itself is your computer (or your cloud environment), and the shipping containers house your applications.

It may also help to think of them as smaller, more lightweight incarnations of virtual machines. While a virtual machine virtualizes the machine’s physical hardware through the use of a hypervisor, a container virtualizes only the operating system. A virtual machine is usually several gigabytes in size, whereas a container is usually less than a gigabyte. The small size and speed of deployment as compared to a traditional virtual machine has given rise to the popularity of designing applications as collections of microservices (several single-purpose services running in containers that, when working together, make up your complete application) instead of monoliths (all of your application code and services running as a single unit, often within a single file).

Deploying your application using containers allows you to package your application code alongside everything required to run it, including its dependencies and an operating system. You know how sometimes you hand code off to someone else, but it doesn’t run for them, so you go “Well, it works on my machine,” and just shrug? Using a container is pretty similar to just deploying your machine. The most popular container engine today is Docker, so that’s what we’ll be using today.

Prerequisites:

Docker
Python3

Before we go into containerizing and deploying our website, let’s make it a little bit more useful. For this, we’re going to be using Flask, a lightweight web framework for Python. Fork and clone this GitHub repository to get the full sample code for part two of this series.

Expanding the Website

Our file structure gets more complicated now that we are building a more dynamic website with server-side routing and throwing it into a Docker container. You will have something like this:

container-tutorial
├── Pulumi.yaml
├── requirements.txt
├── __main__.py
└── website
├── Dockerfile
├── requirements.txt
└── app
├── server.py
├── static
│ ├── normalize.css
│ ├── style.css
│ └── background.jpg
└── templates
├── base.html
├── index.html
├── portfolio.html
└── about.html

Everything contained within the app directory is the website itself. We now have server-side routing, and a few different pages. To run it locally and see what the new website looks like, pip3 install flask to install the Flask web framework and then run python3 server.py from the app directory. Flask will return an IP address where your website is running; navigate there in your browser and click around a bit!

server.py

from flask import Flask, render_template

app = Flask(__name__)

@app.route("/")
def home():
 return render_template("index.html")

@app.route("/about")
def about():
 return render_template("about.html")

@app.route('/portfolio')
def portfolio():
 return render_template("portfolio.html")


if __name__ == '__main__':
 app.run(host='0.0.0.0', port=80, debug=True)

Where before our entire website was made up of a single HTML file, we now have several, and we’re using Flask to handle the routing between them. In this server file, three routs are defined: home, about, and portfolio. Flask handles serving these up for us, and associating a route with a particular HTML file. This way, we get a nice www.mywebsite.com/about URL instead of something like www.mywebsite.com/about.html. Building a website this way also means we have the ability to apply some logic to each of these routes, such as adding database interaction, user login, and passing conditional variables from the server to the templates that will be rendering each page. We aren’t doing any of that yet, but we will!

At the bottom, we’re binding the Flask application to 0.0.0.0:80. You can change that to any other unoccupied local IP address and port you like.

Templating

Flask can make use of a templating engine called Jinja2 to make adding pages to your website a bit less repetitive. You start with one template, in this case called base.html, that contains any HTML you want to exist on every single page.

base.html

<!DOCTYPE html>
<html>
<head>
 <meta charset="utf-8">
 <title>Hello world!</title>
 <link rel="stylesheet" href={{ url_for('static', filename='style.css') }}>
 <link rel="stylesheet" href={{ url_for('static', filename='normalize.css') }}>
</head>
<body>
 <header>
 <div class="logo"><i class="fas fa-cat"></i></div>
 <nav>
 <ul>
 <li {% if request.path == url_for('home') %} class="active" {% endif %}>
 <a href="{{ url_for('home') }}">Home</a>
 </li>
 <li {% if request.path == url_for('about') %} class="active" {% endif %}>
 <a href="{{ url_for('about') }}">About</a>
 </li>
 <li {% if request.path == url_for('portfolio') %} class="active" {% endif %}>
 <a href="{{ url_for('portfolio') }}">Portfolio</a>
 </li>
 </ul>
 </nav>
 <ul class="social">
 <li><a href="http://github.com/katcosgrove" target="_blank"><i class="fab fa-github-alt"></i></a></li>
 <li><a href="http://twitter.com/Dixie3Flatline" target="_blank"><i class="fab fa-twitter"></i></a></li>
 <li><a href="http://linkedin.com/in/katcosgrove" target="_blank"><i class="fab fa-linkedin-in"></i></a></li>
 </ul>
 </header>
{% block content %}{% endblock %}
</body>
<script src="https://kit.fontawesome.com/b4747495ea.js" crossorigin="anonymous"></script>
</html>

This file includes some metadata, stylesheets, the header, navigation, and any Javascript we want to link in. All of the content in this file will exist on every page. Below the header, in the body, you’ll see {% block content %} {% endblock %}. That’s where additional, page-specific content will be added.

index.html

{% extends 'base.html' %}

{% block content %}

<div class="content">
 <h1>Your Name</h1>
 <h3>Job Title at Company</h3>
</div>

{% endblock %}

This is all that exists in our index.html now. The first directive tells Jinja2 that this bit of HTML goes in the base.html template, and the remaining two wrap the content we want to insert. The same thing is happening in about.html and portfolio.html. Neat, right? Jinja2 is not unique to Flask, so you can use this templating engine with another web framework if you prefer.

While we could deploy this as-is, it’s a bit unwieldy. Let’s wrap it up into a container.

Dockerizing our Website

In the website directory, we have something called a Dockerfile. Dockerfiles tell the Docker engine what to do with your application, how your container should behave with respect to the wider internet or other containers, and what needs to be done inside of the container for your application to run. Ours looks like this:

FROM ubuntu:20.04

COPY app /app

WORKDIR /app

EXPOSE 80

RUN apt-get update && \
 apt install -y gcc python3-dev python3-pip python-markupsafe

COPY requirements.txt /app

RUN pip3 install -r requirements.txt

ENTRYPOINT [ "python3" ]

CMD [ "server.py" ]

This Dockerfile says that our container should be running ubuntu:20.04 as its operating system. It will pull the Ubuntu image from Docker Hub, their public image registry, though you can pull from another registry here as well. The COPY directive moves our website’s files (the app directory) into the container. We then set our working directory for all future commands run inside of the container to /app to reduce the amount of typing we have to do later on, update Ubuntu, and install some dependencies using both apt and from the requirements.txt file we also copy over. Lastly, an entrypoint and command to actually start our application are defined. There is a slightly less verbose way to start the application, but this way of defining an ENTRYPOINT and CMD is fairly common, so it’s worth seeing here.

To see this run locally, we first need to build and tag the image. From the same directory as your Dockerfile, run the following command:

docker build --tag container-tutorial:latest .

We are calling the docker CLI, telling it we want to build a container, and indicating that we want to tag it at the same time. The tag isn’t strictly necessary for the container to run, but it does make the container easier to identify and interact with. We’re also assigning it a version of latest. Note the trailing dot at the end of the command, which is the part of the command that indicates the location of the Dockerfile we want to build.

Run docker images to see a list of all images you have built. Something like this should be in the list:

cloud-systems latest 0ce569ac0360 10 days ago 408MB

Now the container is built, we need to run it and forward the container’s port to a local port so we can see our site.

docker run -d -p 80:80 container-tutorial

There’s a lot going on in that command, so let’s take a closer look. the -d flag is short for --detach, and it tells the Docker engine that we want to print the container’s ID and run it in the background. The -p flag is short for --publish, and it tells the Docker engine to publish the container’s port to the host. In this case, port 80.

Run docker ps to get a list of all running containers, and you’ll see something like this:

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
f95362faf3cd container-tutorial "python3 server.py" 7 days ago Up 7 days 0.0.0.0:80->80/tcp, :::80->80/tcp affectionate_jackson

That’s our website! You can see the container ID, the image tag, the commands that ran for it to start the application, its host, the container port, and the port it forwarded to. Go to localhost in your browser, and the website is up!

We’re hosting this locally, though. It’s not accessible by the wider internet, and even if it was, our machines would be dealing with all of the traffic. There’s nothing in place to distribute traffic or restrict access. Worry not, cloud services exist for that, too. In the next in this series, we’ll take our containerized website and deploy it to AWS Elastic Container Service, complete with AWS networking configuration, IAM roles, and AWS Fargate!

How to Build a Container Registry

Sophia Parafina — Tue, 16 Feb 2021 00:00:00 +0000

Whether you are working with Kubernetes or serverless, your application uses containers. If you use the Docker desktop client, images are pushed to Docker Hub by default. Pulling images from Docker Hub is convenient, but there are many reasons to store images in your own registry. For example, Docker Hub doesn’t guarantee to produce the same image on repeated pulls, i.e., your base image might have changed. It’s also possible to inadvertently expose secrets in an intermediate image used to build the image stored on Docker Hub. There is also the possibility of vulnerabilities in even official images. This article shows how to create a repository and how to build and push images to that repository

Container registry offerings

AWS provides the Elastic Container Registry (ECR), Azure has Container Registry, and Google has it’s Container Registry. Each provider has associated services unique to their offering, but all support Docker or OCI compliant images.

Build it

Let’s examine how to create a registry with the provider of your choice. In these examples, we create a registry, build a Docker image, and push the image to the registry. The application used for the image is NGINX.

Choose your cloud provider to learn how to build a registry.

In this example, we create an ECR repository configured to scan an image’s Operating System components. Scanning for vulnerabilities in an application is currently out of scope. We also set a policy for the repository that controls the actions allowed and a lifecycle policy that expires an image after a set time.

With Pulumi, it’s possible to build an image locally using Docker and push it to your repository. To push the image, we obtain the credentials required to push from the registry. Finally, we export the credentials and the URL for the registry. Read more about ECR in the API Reference.

import * as docker from "@pulumi/docker";
import * as aws from "@pulumi/aws";

// Create a repository and configure to scan the image on push
const repo = new aws.ecr.Repository("myrepository", {
 imageScanningConfiguration: {
 scanOnPush: true
 },
 imageTagMutability: "MUTABLE",
});

// Set a use policy for the repository
const repositoryPolicy = new aws.ecr.RepositoryPolicy("myrepositorypolicy", {
 repository: repo.id,
 policy: JSON.stringify({
 Version: "2012-10-17",
 Statement: [{
 Sid: "new policy",
 Effect: "Allow",
 Principal: "*",
 Action: [
 "ecr:GetDownloadUrlForLayer",
 "ecr:BatchGetImage",
 "ecr:BatchCheckLayerAvailability",
 "ecr:PutImage",
 "ecr:InitiateLayerUpload",
 "ecr:UploadLayerPart",
 "ecr:CompleteLayerUpload",
 "ecr:DescribeRepositories",
 "ecr:GetRepositoryPolicy",
 "ecr:ListImages",
 "ecr:DeleteRepository",
 "ecr:BatchDeleteImage",
 "ecr:SetRepositoryPolicy",
 "ecr:DeleteRepositoryPolicy"
 ]
 }]
 })
});

// Set a policy to control the lifecycle of an image
const lifecyclePolicy = new aws.ecr.LifecyclePolicy("mylifecyclepolicy", {
 repository: repo.id,
 policy: JSON.stringify({
 rules: [{
 rulePriority: 1,
 description: "Expire images older than 14 days",
 selection: {
 tagStatus: "untagged",
 countType: "sinceImagePushed",
 countUnit: "days",
 countNumber: 14
 },
 action: {
 type: "expire"
 }
 }]
 })
});

// Get the repository credentials we use to push to the repository
const repoCreds = repo.registryId.apply(async (registryId) => {
 const credentials = await aws.ecr.getCredentials({
 registryId: registryId,
 });
 const decodedCredentials = Buffer.from(credentials.authorizationToken, "base64").toString();
 const [username, password] = decodedCredentials.split(":");
 return { server: credentials.proxyEndpoint, username, password };
});

// Create a new image and push to the repository
const image = new docker.Image("myapp", {
 imageName: repo.repositoryUrl,
 build: "./app",
 registry: repoCreds,
})

// Export credentials and URL to the repository
export const credentials = repoCreds;
export const repoEndpoint = repo.repositoryUrl;

In this example, we create an Azure Resource Group to contain the resources for the registry, such as the App Service that hosts the registry.

We instantiate a registry with the containerservice module and use the Image module in the Docker package to build and push the image to the registry. We export the registry URL and the username and password in case we should want to push or pull and image using the Docker CLI.

import * as azure from "@pulumi/azure";
import * as docker from "@pulumi/docker";
import * as pulumi from "@pulumi/pulumi";

// Create an Azure Resource Group
const resourceGroup = new azure.core.ResourceGroup("examples");

// Create a dedicated App Service Plan for Linux App Services
const plan = new azure.appservice.Plan("linux-apps", {
 resourceGroupName: resourceGroup.name,
 kind: "Linux",
 reserved: true,
 sku: {
 tier: "Basic",
 size: "B1",
 },
});

const repo = new azure.containerservice.Registry("myrepository", {
 resourceGroupName: resourceGroup.name,
 sku: "Basic",
 adminEnabled: true,
});

const myImage = new docker.Image("myapp", {
 imageName: pulumi.interpolate`${repo.loginServer}/${"myapp"}:v1.0.0`,
 build: {
 context: `./${"app"}`,
 },
 registry: {
 server: repo.loginServer,
 username: repo.adminUsername,
 password: repo.adminPassword,
 },
});

export const server = repo.loginServer;
export const username = repo.adminUsername;
export const password = repo.adminPassword;

In this example, we’ll use the configuration and credentials from the gcloud CLI to build an image and push it into the GCP registry. Make sure the GCP project is set and you are logged into GCP and Docker is configured to use the GCR,

$ gcloud init
$ gcloud auth login
$ gcloud auth configure-docker

We use the Image module in the Docker package to build and push the image to the registry. We export the registry URL and the username and password in case we should want to push or pull an image using the Docker CLI.

import * as docker from "@pulumi/docker";
import * as gcp from "@pulumi/gcp";
import * as pulumi from "@pulumi/pulumi";

// Build and push image to gcr repository

const imageName = "myapp";

const myImage = new docker.Image(imageName, {
 imageName: pulumi.interpolate`gcr.io/${gcp.config.project}/${imageName}:latest`,
 build: {
 context: "./app",
 },
});

// Export the repository end point
export const repoEndpoint = pulumi.interpolate`gcr.io/${gcp.config.project}`;

Learn more

Container registries are just one of the many resources used for deploying modern applications. Implementations among cloud service providers differ by the functionality they offer and how they are deployed. The commonality among them is that they provide a secure place to store and retrieve Docker or OCI compliant container images. Explore how to create and manage resources for the cloud service provider of your choice with Pulumi. Great places to start are:

Build and publish container images to any cloud with Infrastructure as Code

Joe Duffy — Tue, 08 Dec 2020 00:00:00 +0000

Going from a containerized application to a service running in the cloud requires a few steps beyond an application’s normal build-and-test cycle. Namely, it means building and publishing a container image in a registry and then consuming that image from your target environment, whether that’s Kubernetes, Amazon ECS, or another container orchestrator. It’s not enough to just write a Dockerfile — you will need to pick a container registry, decide whether that registry should be public or private, authenticate against it, and ideally automate deploying subsequent updates. Infrastructure as code to the rescue! In this article, we’ll see how to build, publish, and consume a simple container image across any cloud, using just a few lines of code.

Approach

The general approach will be to create a new infrastructure as code project that

Prepares a container registry, either public or private
Builds and publishes your container image to that registry
Optionally, consumes the resulting image URL from a containerized task definition in Kubernetes, Amazon ECS, or any other container orchestrator

All told, this will be just a few dozen lines of code. This article demonstrates doing this in AWS, Azure, Google Cloud, DigitalOcean, and Docker Hub, and offers code examples in each supported Pulumi language, namely Python, JavaScript, TypeScript, Go, and C#. These steps will work for any application that has a Dockerfile and is buildable by Docker. In principle, similar steps could be applied if you prefer to build your container image using different means, such as Buildpack.

For purposes of illustration, we’ll create a simple Nginx web server whose Dockerfile contains:

FROM nginx
RUN echo "<h1>Hello, World!</h1>" > \
 /usr/share/nginx/html/index.html

Now, let’s dive in!

Prepare a Container Registry

The first step is to prepare a new container registry. A registry holds one or more repositories, each of which can store and serve many different container images with different tags and versions. Afterward we’ll show how to build and publish to this registry.

The specific details of how to prepare your registry differ by cloud provider, often significantly, particularly when it comes to authenticating. Pick your cloud provider to see the details:

Amazon Elastic Container Registry (ECR)

Amazon Elastic Container Registry (ECR) provides managed Docker container hosting that makes it easy to run containerized applications in your AWS account using Amazon Elastic Container Service (ECS) and Elastic Kubernetes Service (EKS). Each account has a default registry per region, and each registry may have any number of repositories, each for a different Docker image. Each repository can store many versions of that particular image.

Create a New Project

To start, create a new project and ensure it is configured to use your AWS account, and then scaffold your project with the imports and overall program structure that we will fill in one piece at a time:

var aws = require("@pulumi/aws");
var docker = require("@pulumi/docker");

// [Placeholder 1: Create a private ECR registry.]

// [Placeholder 2: Get registry info (creds and endpoint).]

// [Placeholder 3: Build and publish the container image.]

import * as aws from "@pulumi/aws";
import * as docker from "@pulumi/docker";

// [Placeholder 1: Create a private ECR registry.]

// [Placeholder 2: Get registry info (creds and endpoint).]

// [Placeholder 3: Build and publish the container image.]

import base64
import pulumi
import pulumi_aws as aws
import pulumi_docker as docker

# [Placeholder 1: Create a private ECR registry.]

# [Placeholder 2: Get registry info (creds and endpoint).]

# [Placeholder 3: Build and publish the container image.]

package main

import (
 "encoding/base64"
 "errors"
 "strings"

 "github.com/pulumi/pulumi-aws/sdk/v2/go/aws/ecr"
 "github.com/pulumi/pulumi-docker/sdk/v2/go/docker"
 "github.com/pulumi/pulumi/sdk/v2/go/pulumi"
)

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 // [Placeholder 1: Create a private ECR registry.]

 // [Placeholder 2: Get registry info (creds and endpoint).]

 // [Placeholder 3: Build and publish the container image.]
 return nil
 })
}

using System;
using System.Collections.Generic;
using System.Text;
using System.Threading.Tasks;
using Pulumi;
using Pulumi.Aws.Ecr;
using Pulumi.Docker;

class Program
{
 static Task<int> Main() => Deployment.RunAsync(async () => {
 // [Placeholder 1: Create a private ECR repository.]

 // [Placeholder 2: Get registry info (creds and endpoint).]

 // [Placeholder 3: Build and publish the container image.]
 }
}

Provision an ECR Repository

Next, declare a new ECR repository resource:

// Create a private ECR repository.
var repo = new aws.ecr.Repository("my-repo");

// Create a private ECR repository.
const repo = new aws.ecr.Repository("my-repo");

# Create a private ECR repository.
repo = aws.ecr.Repository('my-repo')

// Create a private ECR repository.
repo, err := ecr.NewRepository(ctx, "my-repo", nil)
if err != nil {
 return err
}

// Create a private ECR repository.
var repo = new Repository("my-repo");

Authenticate with Temporary ECR Access Token

Next, we will need to generate authentication information to access the repository to build and publish our image. ECR supports this in multiple different ways; however, here, we will demonstrate generating a temporary access token:

// Get registry info (creds and endpoint).
var imageName = repo.repositoryUrl;
var registryInfo = repo.registryId.apply(id => {
 return aws.ecr.getCredentials({ registryId: id }).then(credentials => {
 var decodedCredentials = Buffer.from(credentials.authorizationToken, "base64").toString();
 var [username, password] = decodedCredentials.split(":");
 if (!password || !username) {
 throw new Error("Invalid credentials");
 }
 return {
 server: credentials.proxyEndpoint,
 username: username,
 password: password,
 };
 });
});

// Get registry info (creds and endpoint).
const imageName = repo.repositoryUrl;
const registryInfo = repo.registryId.apply(async id => {
 const credentials = await aws.ecr.getCredentials({ registryId: id });
 const decodedCredentials = Buffer.from(credentials.authorizationToken, "base64").toString();
 const [username, password] = decodedCredentials.split(":");
 if (!password || !username) {
 throw new Error("Invalid credentials");
 }
 return {
 server: credentials.proxyEndpoint,
 username: username,
 password: password,
 };
});

# Get registry info (creds and endpoint).
def getRegistryInfo(rid):
 creds = aws.ecr.get_credentials(registry_id=rid)
 decoded = base64.b64decode(creds.authorization_token).decode()
 parts = decoded.split(':')
 if len(parts) != 2:
 raise Exception("Invalid credentials")
 return docker.ImageRegistry(creds.proxy_endpoint, parts[0], parts[1])
image_name = repo.repository_url
registry_info = repo.registry_id.apply(getRegistryInfo)

// Get registry info (creds and endpoint).
imageName := repo.RepositoryUrl
registryInfo := repo.RegistryId.ApplyT(func(id string) (docker.ImageRegistry, error) {
 creds, err := ecr.GetCredentials(ctx, &ecr.GetCredentialsArgs{RegistryId: id})
 if err != nil {
 return docker.ImageRegistry{}, err
 }
 decoded, err := base64.StdEncoding.DecodeString(creds.AuthorizationToken)
 if err != nil {
 return docker.ImageRegistry{}, err
 }
 parts := strings.Split(string(decoded), ":")
 if len(parts) != 2 {
 return docker.ImageRegistry{}, errors.New("Invalid credentials")
 }
 return docker.ImageRegistry{
 Server: creds.ProxyEndpoint,
 Username: parts[0],
 Password: parts[1],
 }, nil
}).(docker.ImageRegistryOutput)

// Get registry info (creds and endpoint).
var imageName = repo.RepositoryUrl;
var registryInfo = repo.RegistryId.Apply(async (id) =>
{
 var creds = await GetCredentials.InvokeAsync(new GetCredentialsArgs { RegistryId = id });
 var decodedData = Convert.FromBase64String(creds.AuthorizationToken);
 var decoded = ASCIIEncoding.ASCII.GetString(decodedData);

 var parts = decoded.Split(':');
 if (parts.Length != 2)
 {
 throw new Exception("Invalid credentials");
 }

 return new ImageRegistry
 {
 Server = creds.ProxyEndpoint,
 Username = parts[0],
 Password = parts[1],
 };
});

Alternatively, Authenticate with ECR Credential Helper

An alternative approach ECR supports is to use the Docker credential helper from Amazon, which integrates with local IAM settings, adds smart caching, and removes the need for Docker to login. If you elect to go this route, leave out the username/password parts of the docker.ImageRegistry:

// Get registry info (creds and endpoint).
var imageName = repo.repositoryUrl;
var registryInfo = undefined; // use ECR credentials helper.

// Get registry info (creds and endpoint).
const imageName = repo.repositoryUrl;
const registryInfo = undefined; // use ECR credentials helper.

# Get registry info (creds and endpoint).
image_name = repo.repository_url
registry_info = None # use ECR credentials helper.

// Get registry info (creds and endpoint).
imageName := repo.RepositoryUrl
registryInfo := docker.ImageRegistryArgs{} // use ECR credentials helper.

// Get registry info (creds and endpoint).
var imageName = repo.RepositoryUrl;
// Omit registryInfo and use ECR credentials helper.

Learn More About ECR

ECR offers many additional options not shown here. This includes configuring advanced IAM permissions, enabling image vulnerability scanning, managing the lifetime of images so that older, unused images are deleted based on configured policies, encrypting images, and more. For details on these advanced capabilities and more, refer to Pulumi’s ECR user guide, Pulumi’s ECR API reference, or Amazon’s product documentation.

To view another cloud provider’s registry details, select a new cloud in the switcher above.

Azure Container Registry (ACR)

Azure Container Registry (ACR) allows you to build, store, secure, scan, replicate, and manage container images and artifacts using a fully managed and geo-replicated instance of OCI distribution. This makes it easy to deploy containerized workloads to native Azure services like Azure Kubernetes Service (AKS), Red Hat OpenShift, and App Service. Each registry is capable of storing and serving multiple versions of multiple container images.

Create a New Project

To start, create a new project and ensure it is configured to use your Azure account, and then scaffold your project with the imports and overall program structure that we will fill in one piece at a time:

var azure = require("@pulumi/azure");
var docker = require("@pulumi/docker");

// [Placeholder 1: Create a private ACR registry.]

// [Placeholder 2: Get registry info (creds and endpoint).]

// [Placeholder 3: Build and publish the container image.]

import * as azure from "@pulumi/azure";
import * as docker from "@pulumi/docker";

// [Placeholder 1: Create a private ACR registry.]

// [Placeholder 2: Get registry info (creds and endpoint).]

// [Placeholder 3: Build and publish the container image.]

import pulumi
import pulumi_azure as azure
import pulumi_docker as docker

# [Placeholder 1: Create a private ACR registry.]

# [Placeholder 2: Get registry info (creds and endpoint).]

# [Placeholder 3: Build and publish the container image.]

package main

import (
 "github.com/pulumi/pulumi-azure/sdk/v2/go/azure/containerservice"
 "github.com/pulumi/pulumi-azure/sdk/v2/go/azure/core"
 "github.com/pulumi/pulumi-docker/sdk/v2/go/docker"
 "github.com/pulumi/pulumi/sdk/v2/go/pulumi"
)

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 // [Placeholder 1: Create a private ECR registry.]

 // [Placeholder 2: Get registry info (creds and endpoint).]

 // [Placeholder 3: Build and publish the container image.]
 return nil
 })
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Pulumi;
using Pulumi.Azure.Core;
using Pulumi.Azure.ContainerService;
using Pulumi.Docker;

class Program
{
 static Task<int> Main() => Deployment.RunAsync(async () => {
 // [Placeholder 1: Create a private ECR registry.]

 // [Placeholder 2: Get registry info (creds and endpoint).]

 // [Placeholder 3: Build and publish the container image.]
 }
}

Provision a New ACR Registry

Next, declare a new ACR registry resource. To create a new registry, we need an Azure resource group; here we will create a new one, but feel free to use an existing one by passing its name in the resource group’s place:

// Create a private ACR registry.
var rg = new azure.core.ResourceGroup("myrg");
var registry = new azure.containerservice.Registry("myregistry", {
 resourceGroupName: rg.name,
 adminEnabled: true,
 sku: "Basic",
});

// Create a private ACR registry.
const rg = new azure.core.ResourceGroup("myrg");
const registry = new azure.containerservice.Registry("myregistry", {
 resourceGroupName: rg.name,
 adminEnabled: true,
 sku: "Basic",
});

# Create a private ACR registry.
rg = azure.core.ResourceGroup('myrg')
registry = azure.containerservice.Registry('myregistry',
 resource_group_name=rg.name,
 admin_enabled=True,
 sku='Basic'
)

// Create a private ACR registry.
rg, err := core.NewResourceGroup(ctx, "myrg", nil)
if err != nil {
 return err
}
registry, err := containerservice.NewRegistry(ctx, "my-repo", &containerservice.RegistryArgs{
 ResourceGroupName: rg.Name,
 AdminEnabled: pulumi.Bool(true),
 Sku: pulumi.String("Basic"),
})
if err != nil {
 return err
}

// Create a private ACR registry.
var rg = new ResourceGroup("myrg");
var registry = new Registry("myregistry", new RegistryArgs
{
 ResourceGroupName = rg.Name,
 AdminEnabled = true,
 Sku = "basic"
});

Authenticate with Admin Account

Now we need to gather up the image name and registry authentication information, which has been auto-generated by Azure, in preparation for building and publishing to it. For this simple example, we have enabled admin access, which we will use to authenticate:

// Get registry info (creds and endpoint).
var imageName = registry.loginServer.apply(s => `${s}/myapp`);
var registryInfo = {
 server: registry.loginServer,
 username: registry.adminUsername,
 password: registry.adminPassword,
};

// Get registry info (creds and endpoint).
const imageName = registry.loginServer.apply(s => `${s}/myapp`);
const registryInfo = {
 server: registry.loginServer,
 username: registry.adminUsername,
 password: registry.adminPassword,
};

# Get registry info (creds and endpoint).
image_name = registry.login_server.apply(lambda s: f'{s}/myapp')
registry_info = docker.ImageRegistry(
 server=registry.login_server,
 username=registry.admin_username,
 password=registry.admin_password
)

// Get registry info (creds and endpoint).
imageName := pulumi.Sprintf("%s/myapp", registry.LoginServer)
registryInfo := docker.ImageRegistryArgs{
 Server: registry.LoginServer,
 Username: registry.AdminUsername,
 Password: registry.AdminPassword,
}

// Get registry info (creds and endpoint).
var imageName = Output.Format($"{registry.LoginServer}/myapp");
var registryInfo = new ImageRegistry
{
 Server = registry.LoginServer,
 Username = registry.AdminUsername,
 Password = registry.AdminPassword,
};

Alternatively, Authenticate with ActiveDirectory Service Principal

Although enabling admin access is “easy”, it isn’t the most secure approach. An alternative is to set “admin enabled” to false when declaring our registry, provision or assign an ActiveDirectory service principal with an acrpush role scoped to our registry, and use that for authentication instead:

// New imports:
var azuread = require("@pulumi/azuread");
var random = require("@pulumi/random");

// [As before...]

// Get registry info (creds and endpoint).
var sp = new azuread.ServicePrincipal("mysp", {
 applicationId: new azuread.Application("myspapp").applicationId,
});
var spPassword = new azuread.ServicePrincipalPassword("mysp-pass", {
 servicePrincipalId: sp.id,
 value: new random.RandomPassword("mypass", {
 length: 32,
 }, { additionalSecretOutputs: [ "result" ] }).result,
 endDateRelative: "8760h",
});
var spAuth = new azure.authorization.Assignment("myauth", {
 scope: registry.id,
 roleDefinitionName: "acrpush",
 principalId: sp.id,
});
var registryInfo = {
 server: registry.loginServer,
 username: sp.applicationId,
 password: spAuth.id.apply(_ => spPassword.value),
};

// New imports:
import * as azuread from "@pulumi/azuread";
import * as random from "@pulumi/random";

// [As before...]

// Get registry info (creds and endpoint).
const sp = new azuread.ServicePrincipal("mysp", {
 applicationId: new azuread.Application("myspapp").applicationId,
});
const spPassword = new azuread.ServicePrincipalPassword("mysp-pass", {
 servicePrincipalId: sp.id,
 value: new random.RandomPassword("mypass", {
 length: 32,
 }, { additionalSecretOutputs: [ "result" ] }).result,
 endDateRelative: "8760h",
});
const spAuth = new azure.authorization.Assignment("myauth", {
 scope: registry.id,
 roleDefinitionName: "acrpush",
 principalId: sp.id,
});
const registryInfo = {
 server: registry.loginServer,
 username: sp.applicationId,
 password: spAuth.id.apply(_ => spPassword.value),
};

# New imports:
import pulumi_azuread as azuread
import pulumi_random as random

# [As before...]

# Get registry info (creds and endpoint).
image_name = registry.login_server.apply(lambda s: f'{s}/myapp')
sp = azuread.ServicePrincipal('mysp',
 application_id=azuread.Application('myspapp').application_id,
)
sp_password = azuread.ServicePrincipalPassword('mysp-pass',
 service_principal_id=sp.id,
 value=random.RandomPassword('mypass',
 length=32,
 opts=pulumi.ResourceOptions(additional_secret_outputs=['result'])
 ).result,
 end_date_relative='8760h',
)
sp_auth = azure.authorization.Assignment('myauth',
 scope=registry.id,
 role_definition_name='acrpush',
 principal_id=sp.id,
)
registry_info = docker.ImageRegistry(
 server=registry.login_server,
 username=sp.application_id,
 password=sp_auth.id.apply(lambda _: sp_password.value),
)

// New imports:
import (
 "github.com/pulumi/pulumi-azure/sdk/v2/go/azure/authorization"
 "github.com/pulumi/pulumi-azuread/sdk/v2/go/azuread"
 "github.com/pulumi/pulumi-random/sdk/v2/go/random"
)

// [As before...]

// Get registry info (creds and endpoint).
imageName := pulumi.Sprintf("%s/myapp", registry.LoginServer)
spApp, err := azuread.NewApplication(ctx, "myspapp", nil)
if err != nil {
 return err
}
sp, err := azuread.NewServicePrincipal(ctx, "mysp", &azuread.ServicePrincipalArgs{
 ApplicationId: spApp.ApplicationId,
})
if err != nil {
 return err
}
password, err := random.NewRandomPassword(ctx, "mypass",
 &random.RandomPasswordArgs{
 Length: pulumi.Int32(32),
 },
 pulumi.AdditionalSecretOutputs([]string{"result"}),
)
if err != nil {
 return err
}
spPassword, err := azuread.NewServicePrincipalPassword(ctx, "mysp-pass", &azuread.ServicePrincipalPasswordArgs{
 ServicePrincipalId: sp.ID(),
 Value: password.Result,
 EndDateRelative: pulumi.String("8760h"),
})
if err != nil {
 return err
}
apAuth, err := authorization.NewAssignment(ctx, "myauth", &authorization.AssignmentArgs{
 Scope: registry.ID(),
 RoleDefinitionName: pulumi.String("acrpush"),
 PrincipalId: sp.ID(),
})
if err != nil {
 return err
}
registryInfo := docker.ImageRegistryArgs{
 Server: registry.LoginServer,
 Username: sp.ApplicationId,
 Password: spPassword.Value,
}

// New imports:
using Pulumi.Azure.Authorization;
using AAD = Pulumi.AzureAD;
using Pulumi.Random;

// [As before...]

// Get registry info (creds and endpoint).
var imageName = Output.Format($"{registry.LoginServer}/myapp");
var sp = new AAD.ServicePrincipal("mysp", new AAD.ServicePrincipalArgs
{
 ApplicationId = new AAD.Application("myspapp").ApplicationId,
});
var spPassword = new AAD.ServicePrincipalPassword("mysp-pass", new AAD.ServicePrincipalPasswordArgs
{
 ServicePrincipalId = sp.Id,
 Value = new RandomPassword("mypass",
 new RandomPasswordArgs
 {
 Length = 32,
 },
 new CustomResourceOptions { AdditionalSecretOutputs = { "result" } }
 ).Result,
 EndDateRelative = "8760h",
});
var spAuth = new Assignment("myauth", new AssignmentArgs
{
 Scope = registry.Id,
 RoleDefinitionName = "acrpush",
 PrincipalId = sp.Id,
});
var registryInfo = new Docker.ImageRegistry
{
 Server = registry.LoginServer,
 Username = sp.ApplicationId,
 Password = spAuth.Id.Apply(_ => spPassword.Value),
};

Learn More About ACR

ACR offers advanced functionality not shown here, including configuring retention policies, storage account details, and geo-replication options. For more details on these and more, see Pulumi’s Azure-Native or Azure API documentation, or Azure’s product page.

To view another cloud provider’s registry details, select a new cloud in the switcher above.

Google Container Registry (GCR)

Google Container Registry (GCR) enables you to store, manage, and secure your Docker container images. It includes built-in security vulnerability scanning and fast, high-availability access by storing images in regional private repositories across the world. This makes it easy to deploy custom application images to Google Kubernetes Engine (GKE), App Engine, or Cloud Run. Each account has a default registry per project per region, backed by Google Cloud Storage (GCS), and each registry is capable of storing many images and many versions.

Create a New Project

To start, create a new project and ensure it is configured to use your Google Cloud account, then scaffold your project with the imports and overall program structure that we will fill in one piece at a time:

var gcp = require("@pulumi/gcp");
var docker = require("@pulumi/docker");

// [Placeholder 1: Create a private GCR registry.]

// [Placeholder 2: Get registry info (creds and endpoint).]

// [Placeholder 3: Build and publish the container image.]

import * as gcp from "@pulumi/gcp";
import * as docker from "@pulumi/docker";

// [Placeholder 1: Create a private GCR registry.]

// [Placeholder 2: Get registry info (creds and endpoint).]

// [Placeholder 3: Build and publish the container image.]

import pulumi
import pulumi_gcp as gcp
import pulumi_docker as docker

# [Placeholder 1: Create a private GCR registry.]

# [Placeholder 2: Get registry info (creds and endpoint).]

# [Placeholder 3: Build and publish the container image.]

package main

import (
 "encoding/base64"
 "errors"
 "strings"

 "github.com/pulumi/pulumi-docker/sdk/v2/go/docker"
 "github.com/pulumi/pulumi-gcp/sdk/v2/go/gcp/container"
 "github.com/pulumi/pulumi/sdk/v2/go/pulumi"
)

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 // [Placeholder 1: Create a private GCR registry.]

 // [Placeholder 2: Get registry info (creds and endpoint).]

 // [Placeholder 3: Build and publish the container image.]
 return nil
 })
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Pulumi;
using Pulumi.Docker;
using Pulumi.Gcp.Container;

class Program
{
 static Task<int> Main() => Deployment.RunAsync(async () => {
 // [Placeholder 1: Create a private GCR registry.]

 // [Placeholder 2: Get registry info (creds and endpoint).]

 // [Placeholder 3: Build and publish the container image.]
 }
}

Ensure Your GCR Registry is Ready

Google Cloud automatically provisions a managed project-wide registry as needed. To ensure our Google Cloud registry is ready, we allocate a registry object, and then fetch the autogenerated repository URL that we can use for images:

// Create a private GCR registry.
var registry = new gcp.container.Registry("my-registry");
var registryUrl = registry.id.apply(_ =>
 gcp.container.getRegistryRepository().then(reg => reg.repositoryUrl));

// Create a private GCR registry.
const registry = new gcp.container.Registry("my-registry");
const registryUrl = registry.id.apply(_ =>
 gcp.container.getRegistryRepository().then(reg => reg.repositoryUrl));

# Create a private GCR repository.
registry = gcp.container.Registry('my-registry')
registry_url = registry.id.apply(lambda _: gcp.container.get_registry_repository().repository_url)

// Create a private GCR registry.
registry, err := container.NewRegistry(ctx, "my-registry", nil)
if err != nil {
 return err
}
registryUrl := registry.ID().ApplyString(func(_ string) (string, error) {
 rep, err := container.GetRegistryRepository(ctx, nil)
 if err != nil {
 return "", err
 }
 return rep.RepositoryUrl, nil
})

// Create a private GCR registry.
var registry = new Registry("my-registry");
var registryUrl = registry.Id.Apply(async _ => {
 return (await GetRegistryRepository.InvokeAsync()).RepositoryUrl;
});

Below we will append the container repository name to this registry URL.

Authenticate with the Google Cloud SDK

Google Cloud offers several mechanisms to authenticate to your registry; however, the most secure and preferred option is to use the Google Cloud CLI, gcloud, as a Docker credential helper. After setting up gcloud on your client, no explicit authentication is required in your code — instead, the ambient gcloud authentication settings will be used instead. As a result, we can leave the authentication information blank:

// Get registry info (creds and endpoint).
var imageName = registryUrl.apply(url => `${url}/myapp`);
var registryInfo = undefined; // use gcloud for authentication.

// Get registry info (creds and endpoint).
const imageName = registryUrl.apply(url => `${url}/myapp`);
const registryInfo = undefined; // use gcloud for authentication.

# Get registry info (creds and endpoint).
image_name = registry_url.apply(lambda url: f'{url}/myapp')
registry_info = None # use gcloud for authentication.

// Get registry info (creds and endpoint).
imageName := pulumi.Sprintf("%s/myapp", registryUrl)
registryInfo := docker.ImageRegistryArgs{} // use gcloud for authentication.

// Get registry info (creds and endpoint).
var imageName = Output.Format($"{registryUrl}/myapp");
// Omit registryInfo and use gcloud for authentication.

Learn More About GCR

GCR uses Google Cloud Storage to store images, which may be configured separately, including configuring IAM and lifecycle policies. For more details on this, please refer to Pulumi’s Google Cloud API or Google’s own Container Registry documentation.

To view another cloud provider’s registry details, select a new cloud in the switcher above.

DigitalOcean Container Registry

DigitalOcean’s Container Registry is an easy way to store and manage private container images for your applications for use with DigitalOcean’s managed Kubernetes service.

Create a New Project

To start, create a new project and ensure it is configured to use your DigitalOcean account and then scaffold your project with the imports and overall program structure that we will fill in one piece at a time:

var digitalocean = require("@pulumi/digitalocean");
var docker = require("@pulumi/docker");
var pulumi = require("@pulumi/pulumi");

// [Placeholder 1: Create a private DigitalOcean container registry.]

// [Placeholder 2: Get registry info (creds and endpoint).]

// [Placeholder 3: Build and publish the container image.]

import * as digitalocean from "@pulumi/digitalocean";
import * as docker from "@pulumi/docker";
import * as pulumi from "@pulumi/pulumi";

// [Placeholder 1: Create a private DigitalOcean container registry.]

// [Placeholder 2: Get registry info (creds and endpoint).]

// [Placeholder 3: Build and publish the container image.]

import pulumi
import pulumi_digitalocean as digitalocean
import pulumi_docker as docker

# [Placeholder 1: Create a private DigitalOcean container registry.]

# [Placeholder 2: Get registry info (creds and endpoint).]

# [Placeholder 3: Build and publish the container image.]

package main

import (
 "encoding/base64"
 "encoding/json"
 "errors"
 "strings"

 "github.com/pulumi/pulumi-digitalocean/sdk/v2/go/digitalocean"
 "github.com/pulumi/pulumi-docker/sdk/v2/go/docker"
 "github.com/pulumi/pulumi/sdk/v2/go/pulumi"
)

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 // [Placeholder 1: Create a private DigitalOcean container registry.]

 // [Placeholder 2: Get registry info (creds and endpoint).]

 // [Placeholder 3: Build and publish the container image.]
 return nil
 })
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Pulumi;
using Pulumi.DigitalOcean;
using Pulumi.Docker;
using Newtonsoft.Json;

class Program
{
 static Task<int> Main() => Deployment.RunAsync(async () => {
 // [Placeholder 1: Create a private DigitalOcean container registry.]

 // [Placeholder 2: Get registry info (creds and endpoint).]

 // [Placeholder 3: Build and publish the container image.]
 }
}

Create a DigitalOcean Container Registry

Next, declare a new DigitalOcean container registry resource:

// Create a private DigitalOcean Container Registry.
var registry = new digitalocean.ContainerRegistry("my-reg", {
 subscriptionTierSlug: "starter",
});

// Create a private DigitalOcean Container Registry.
const registry = new digitalocean.ContainerRegistry("my-reg", {
 subscriptionTierSlug: "starter",
});

# Create a private DigitalOcean Container Registry.
repo = digitalocean.ContainerRegistry('my-reg',
 subscription_tier_slug='starter',
)

// Create a private DigitalOcean Container Registry.
registry, err := digitalocean.NewContainerRegistry(ctx, "my-reg",
 &digitalocean.ContainerRegistryArgs{
 // SubscriptionTierSlug: pulumi.String("starter"),
 })
if err != nil {
 return err
}

// Create a private DigitalOcean Container Registry.
var registry = new ContainerRegistry("my-reg", new ContainerRegistryArgs
{
 SubscriptionTierSlug = "starter"
});

Authenticate with Temporary Credentials

DigitalOcean supports generating temporary read or read/write credentials that Docker can use to authenticate with your new private container registry, which we’ll now use. This resource returns a new credentials file similar to what the docker login command generates, and we can parse it and base64 decode its contents to discover the temporary username and password. Here, we gather the username and password plus the registry’s URL endpoint in preparation for building and publishing the container image to the newly provisioned registry:

// Get registry info (creds and endpoint) so we can build/publish to it.
var imageName = registry.endpoint.apply(s => `${s}/myapp`);
var creds = new digitalocean.ContainerRegistryDockerCredentials("my-reg-creds", {
 registryName: registry.name,
 write: true,
});
var registryInfo = pulumi.all(
 [creds.dockerCredentials, registry.serverUrl]
).apply(([authJson, serverUrl]) => {
 // We are given a Docker creds file; parse it to find the temp username/password.
 var auths = JSON.parse(authJson);
 var authToken = auths["auths"][serverUrl]["auth"];
 var decoded = Buffer.from(authToken, "base64").toString();
 var [username, password] = decoded.split(":");
 if (!password || !username) {
 throw new Error("Invalid credentials");
 }
 return {
 server: serverUrl,
 username: username,
 password: password,
 };
});

// Get registry info (creds and endpoint) so we can build/publish to it.
const imageName = registry.endpoint.apply(s => `${s}/myapp`);
const creds = new digitalocean.ContainerRegistryDockerCredentials("my-reg-creds", {
 registryName: registry.name,
 write: true,
});
const registryInfo = pulumi.all(
 [creds.dockerCredentials, registry.serverUrl]
).apply(([authJson, serverUrl]) => {
 // We are given a Docker creds file; parse it to find the temp username/password.
 const auths = JSON.parse(authJson);
 const authToken = auths["auths"][serverUrl]["auth"];
 const decoded = Buffer.from(authToken, "base64").toString();
 const [username, password] = decoded.split(":");
 if (!password || !username) {
 throw new Error("Invalid credentials");
 }
 return {
 server: serverUrl,
 username: username,
 password: password,
 };
});

# Get registry info (creds and endpoint).
image_name = registry.endpoint.apply(lambda s: f'{s}/myapp')
def getRegistryInfo(info):
 # We are given a Docker creds file; parse it to find the temp username/password.
 auth_json = info[0]
 auths = json.loads(auth_json)
 server_url = info[1]
 auth_token = auths['auths'][server_url]['auth']
 decoded = base64.b64decode(auth_token).decode()
 parts = decoded.split(':')
 if len(parts) != 2:
 raise Exception('Invalid credentials')
 return docker.ImageRegistry(server_url, parts[0], parts[1])
creds = digitalocean.ContainerRegistryDockerCredentials('reg-creds',
 registry_name=registry.name,
 write=True,
)
registry_info = pulumi.Output.all(
 creds.docker_credentials, registry.server_url).apply(getRegistryInfo)

// Get registry info (creds and endpoint).
imageName := pulumi.Sprintf("%s/myapp", registry.Endpoint)
creds, err := digitalocean.NewContainerRegistryDockerCredentials(ctx, "my-reg-creds",
 &digitalocean.ContainerRegistryDockerCredentialsArgs{
 RegistryName: registry.Name,
 Write: pulumi.Bool(true),
 },
)
if err != nil {
 return err
}

registryInfo := pulumi.All(creds.DockerCredentials, registry.ServerUrl).ApplyT(
 func(args []interface{}) (docker.ImageRegistry, error) {
 // We are given a Docker creds file; parse it to find the temp username/password.
 authJson := args[0].(string)
 serverUrl := args[1].(string)
 var auths map[string]interface{}
 if err := json.Unmarshal([]byte(authJson), &auths); err != nil {
 return docker.ImageRegistry{}, err
 }
 authMap := auths["auths"].(map[string]interface{})
 authToken := authMap[serverUrl].(map[string]interface{})["auth"].(string)
 decoded, err := base64.StdEncoding.DecodeString(authToken)
 if err != nil {
 return docker.ImageRegistry{}, err
 }
 parts := strings.Split(string(decoded), ":")
 if len(parts) != 2 {
 return docker.ImageRegistry{}, errors.New("Invalid credentials")
 }
 return docker.ImageRegistry{
 Server: serverUrl,
 Username: parts[0],
 Password: parts[1],
 }, nil
 },
).(docker.ImageRegistryOutput)

// Get registry info (creds and endpoint).
var imageName = Output.Format($"{registry.Endpoint}/myapp");
var registryCreds = new ContainerRegistryDockerCredentials("my-reg-creds",
 new ContainerRegistryDockerCredentialsArgs
 {
 RegistryName = registry.Name,
 Write = true,
 });
var registryInfo = Output.All(
 registryCreds.DockerCredentials, registry.ServerUrl).
 Apply(args =>
 {
 var authJson = args[0];
 var serverUrl = args[1];
 dynamic auths = JsonConvert.DeserializeObject(authJson);
 var authToken = auths["auths"][serverUrl]["auth"];
 var decoded = ASCIIEncoding.ASCII.GetString(authToken);

 var parts = decoded.Split(':');
 if (parts.Length != 2)
 {
 throw new Exception("Invalid credentials");
 }

 return new ImageRegistry
 {
 Server = serverUrl,
 Username = parts[0],
 Password = parts[1],
 };
 });

Learn More About DigitalOcean Container Registry

Each DigitalOcean account may have just a single registry, so you are likely to want to provision that in a separate stack for most “real world” examples. Also, this project uses the lowest subscription tier, "starter", which is inexpensive but quite limited (you may only store a single repository of images). If you would like to use an advanced tier or configure any other options, please refer to Pulumi’s DigitalOcean API or DigitalOcean’s product documentation.

To view another cloud provider’s registry details, select a new cloud in the switcher above.

Docker Hub

Docker offers the Docker Hub as an easy way to store and consume public or private container images from a centralized location to any cloud. To start building and publishing to Docker Hub with infrastructure as code, create a new project and scaffold it with the imports and overall program structure that we will fill in one piece at a time:

var docker = require("@pulumi/docker");
var pulumi = require("@pulumi/pulumi");

// [Placeholder 1: Get registry info (creds and endpoint).]

// [Placeholder 2: Build and publish the container image.]

import * as docker from "@pulumi/docker";
import * as pulumi from "@pulumi/pulumi";

// [Placeholder 1: Get registry info (creds and endpoint).]

// [Placeholder 2: Build and publish the container image.]

import pulumi
import pulumi_docker as docker

# [Placeholder 1: Get registry info (creds and endpoint).]

# [Placeholder 2: Build and publish the container image.]

package main

import (
 "encoding/base64"
 "encoding/json"
 "errors"
 "strings"

 "github.com/pulumi/pulumi-docker/sdk/v2/go/docker"
 "github.com/pulumi/pulumi/sdk/v2/go/pulumi"
)

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 // [Placeholder 1: Get registry info (creds and endpoint).]

 // [Placeholder 2: Build and publish the container image.]
 return nil
 })
}

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Pulumi;
using Pulumi.Docker;

class Program
{
 static Task<int> Main() => Deployment.RunAsync(async () => {
 // [Placeholder 1: Get registry info (creds and endpoint).]

 // [Placeholder 2: Build and publish the container image.]
 }
}

For purposes of this example, you will need to manually provision a repository, and select whether to make it public or private, via the Docker Hub’s UI. Refer to the Docker Hub documentation for details on how to do this. Once you have an account and have set up your registry, create an access token. We will now use your username and this access token to configure authentication so that you can build and publish to your registry.

Because the repository was provisioned outside of the purview of Pulumi, we can jump straight to authenticating. To do this, we will simply use the Pulumi configuration system to store and retrieve authentication information, using the token created above:

// Fetch the Docker Hub auth info from config.
var config = new pulumi.Config();
var username = config.require("dockerUsername");
var password = config.requireSecret("dockerPassword");

// Populate the registry info (creds and endpoint).
var imageName = `${username}/myapp`;
var registryInfo = {
 server: "docker.io",
 username: username,
 password: password,
};

// Fetch the Docker Hub auth info from config.
const config = new pulumi.Config();
const username = config.require("dockerUsername");
const password = config.requireSecret("dockerPassword");

// Populate the registry info (creds and endpoint).
const imageName = `${username}/myapp`;
const registryInfo = {
 server: "docker.io",
 username: username,
 password: password,
};

# Fetch the Docker Hub auth info from config.
config = pulumi.Config()
username = config.require('dockerUsername')
accessToken = config.require_secret('dockerAccessToken')

# Populate the registry info (creds and endpoint).
image_name=f'{username}/myapp',
def get_registry_info(token):
 return docker.ImageRegistry(
 server='docker.io',
 username=username,
 password=token,
 )
registry_info=accessToken.apply(get_registry_info)

// Fetch the Docker Hub auth info from config.
username := config.Require(ctx, "dockerUsername")
password := config.RequireSecret(ctx, "dockerPassword")

// Populate the registry info (creds and endpoint).
imageName := pulumi.String(username + "/myapp")
registryInfo := docker.ImageRegistryArgs{
 Server: pulumi.String("docker.io"),
 Username: pulumi.String(username),
 Password: password.(pulumi.StringOutput),
}

// Fetch the Docker Hub auth info from config.
var config = new Pulumi.Config();
var username = config.Require("dockerUsername");
var password = config.RequireSecret("dockerPassword");

// Populate the registry info (creds and endpoint).
var imageName = $"{username}/myapp";
var registryInfo = new ImageRegistry
{
 Server = "docker.io",
 Username = username,
 Password = password,
};

After writing this code, add your Docker username and password to your Pulumi project:

$ pulumi config set dockerUsername [YOUR USERNAME]
$ pulumi config set --secret dockerAccessToken [YOUR TOKEN]

There are of course other ways to configure this authentication information, however, the Pulumi secrets system ensures that your token is encrypted and safe to use.

To view another cloud provider’s registry details, select a new cloud in the switcher above.

At this stage, we can run pulumi up to check that the program works and to provision any necessary cloud resources.

Build and Publish Your Container

Now we are ready to build and publish your container image to the chosen registry. The Docker provider’s Image component internally uses the Docker engine to perform the necessary steps to carry this out, including building, tagging, capturing, and streaming container build logs as progress is made and pushing the final result.

Simply pass the path to your application’s Dockerfile as the build context, the registry’s URL as the image’s name, and the registry configuration object built up earlier to facilitate authentication:

// [Existing imports ...]
var docker = require("@pulumi/docker");

// [Registry configuration as shown above ...]

// Build and publish the container image.
var image = new docker.Image("my-image", {
 build: "app",
 imageName: imageName,
 registry: registry,
});

// Export the base and specific version image name.
module.exports = {
 baseImageName: image.baseImageName,
 fullImageName: image.imageName,
};

// [Existing imports ...]
import * as docker from "@pulumi/docker";

// [Registry configuration as shown above ...]

// Build and publish the container image.
const image = new docker.Image("my-image", {
 build: "app",
 imageName,
 registry,
});

// Export the base and specific version image name.
export const baseImageName = image.baseImageName;
export const fullImageName = image.imageName;

# [Existing imports ...]
import pulumi_docker as docker

# [Registry configuration as shown above ...]

# Build and publish the container image.
image = docker.Image('my-image',
 build='app',
 image_name=image_name,
 registry=registry_info,
)

# Export the base and specific version image name.
pulumi.export('baseImageName', image.base_image_name)
pulumi.export('fullImageName', image.image_name)

// [Existing imports ...]

import "github.com/pulumi/pulumi-docker/sdk/v2/go/docker"

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 // [Registry configuration as shown above ...]

 // Build and publish the container image.
 image, err := docker.NewImage(ctx, "my-image", &docker.ImageArgs{
 Build: &docker.DockerBuildArgs{Context: pulumi.String("app")},
 ImageName: imageName,
 Registry: registryInfo,
 })

 // Export the base and specific version image name.
 ctx.Export("baseImageName", image.BaseImageName)
 ctx.Export("fullImageName", image.ImageName)
 return nil
 })
}

// [Existing imports ...]

using Pulumi.Docker;

class Program
{
 static Task<int> Main() => Deployment.RunAsync(async () => {
 // [Registry configuration as shown above ...]

 // Build and publish the container image.
 var image = new Image("my-image", new ImageArgs
 {
 Build = new DockerBuild { Context = "app" },
 ImageName = imageName,
 Registry = registryInfo,
 });

 // Export the base and specific version image name.
 return new Dictionary<string, object>
 {
 { "baseImageName", image.BaseImageName },
 { "fullImageName", image.ImageName },
 };
 });
}

Now let’s run pulumi up. If you haven’t already done so, this will provision the cloud resources, as well as build/publish the container image. As the build runs, you will see Docker build output streamed to your terminal:

$ pulumi up
Updating (dev)

 Type Name Status
 + pulumi:pulumi:Stack project-dev created
 ... cloud-specific resources omitted ...
 + └─ docker:image:Image my-image created

Outputs:
 baseImageName: "...cloud-specific url.../my-repo-dc811b0"
 fullImageName: "...cloud-specific url.../my-repo-dc811b0:78d0fce7c2450c15a6153b6b11208fcb6b9edea7bb7ef3b7b6194f3fc101a170"

Also note the base and versioned image URLs are exported as stack outputs. These are optional but have three benefits:

As we see here, the CLI will print them after each deployment.
The CLI can fetch them on-demand, e.g., ‘pulumi stack output fullImageName’, making it easy to script access to these container images.
The Pulumi StackReference component can be used to depend on this stack from another, allowing us to build higher levels of infrastructure that consume these images.

As an example of (2) in action, let’s run the image locally using the exported image name:

$ pulumi stack output fullImageName
...cloud-specific url.../my-repo-dc811b0:78d0fce7c2450c15a6153b6b11208fcb6b9edea7bb7ef3b7b6194f3fc101a170

Note that this requires that our client can pull from our provisioned registry, which may require cloud-specific authentication first.

To redeploy changes to the Dockerfile or anything that image depends on, including application code, rerun pulumi up. It will detect the differences, rebuild and re-push the minimal layer changes necessary to update and retag the repository image, and then export the resulting image name.

To see this in action, change the Dockerfile’s contents to:

FROM nginx
RUN echo "<h1>Hello, World -- from Pulumi!</h1>" > \
 /usr/share/nginx/html/index.html

And then rerun Pulumi – notice how it detects the change, updates the image, and the versioned image hash changes (indicated by the tilde ~):

$ pulumi up
Updating (dev)

 Type Name Status
 + pulumi:pulumi:Stack project-dev created
 ~ └─ docker:image:Image my-image updated

Outputs:
 baseImageName: "...cloud-specific url.../my-repo-dc811b0"
 ~ fullImageName: "...cloud-specific url.../my-repo-dc811b0:78d0fce7c2450c15a6153b6b11208fcb6b9edea7bb7ef3b7b6194f3fc101a170"

The Pulumi Docker Image component supports a number of additional options to control its behavior, including passing build arguments, environment variables, extra options for the Docker build, as well as various controls for image caching. For full details on each of these, refer to the image API documentation.

Consume the Container Image

The same container image URLs exported above can be used as inputs to other resources, including infrastructure that will run your container inside of a container orchestration system such as Kubernetes, Amazon ECS, and so on.

This article assumes you already have a containerized environment to deploy to, like a Kubernetes cluster, and have configured your project accordingly. If not, you can provision one using Pulumi first. Pulumi supports many clouds and infrastructure resources, but here are a few starting points to get up and running with:

This example demonstrates deploying our Nginx web server as a load balanced service within Kubernetes. To do so, we’ll declare our Kubernetes configuration, right inside of our existing program defined above, and export its resulting IP address:

// [Previous imports...]
var k8s = require("@pulumi/kubernetes");

// [Registry, build, etc., code from above...]

// Create a load balanced Kubernetes service using this image, and export its IP.
var appLabels = { app: "myapp" };
var appDep = new k8s.apps.v1.Deployment("app-dep", {
 spec: {
 selector: { matchLabels: appLabels },
 replicas: 3,
 template: {
 metadata: { labels: appLabels },
 spec: {
 containers: [{
 name: "myapp",
 image: image.imageName,
 }],
 },
 },
 },
});
var appSvc = new k8s.core.v1.Service("app-svc", {
 metadata: { labels: appLabels },
 spec: {
 type: "LoadBalancer",
 ports: [{ port: 80, targetPort: 80, protocol: "TCP" }],
 selector: appLabels,
 },
});

module.exports = {
 // [Previous exports...]
 appIp: appSvc.status.loadbalancer.ingress[0].ip,
};

// [Previous imports...]
import * as k8s from "@pulumi/kubernetes";

// [Registry, build, etc, code from above...]

// Create a load balanced Kubernetes service using this image, and export its IP.
const appLabels = { app: "myapp" };
const appDep = new k8s.apps.v1.Deployment("app-dep", {
 spec: {
 selector: { matchLabels: appLabels },
 replicas: 3,
 template: {
 metadata: { labels: appLabels },
 spec: {
 containers: [{
 name: "myapp",
 image: image.imageName,
 }],
 },
 },
 },
});
const appSvc = new k8s.core.v1.Service("app-svc", {
 metadata: { labels: appLabels },
 spec: {
 type: "LoadBalancer",
 ports: [{ port: 80, targetPort: 80, protocol: "TCP" }],
 selector: appLabels,
 },
});
export const appIp = appSvc.status.loadBalancer.ingress[0].ip;

# [Previous imports...]
import pulumi_kubernetes as k8s

# [Registry, build, etc, code from above...]

# Create a load balanced Kubernetes service using this image, and export its IP.
app_labels = { 'app': 'myapp' }
app_dep = k8s.apps.v1.Deployment('app-dep',
 spec={
 'selector': { 'matchLabels': app_labels },
 'replicas': 3,
 'template': {
 'metadata': { 'labels': app_labels },
 'spec': {
 'containers': [{
 'name': 'myapp',
 'image': image.image_name,
 }],
 },
 },
 },
)
app_svc = k8s.core.v1.Service('app-svc',
 metadata={ 'labels': app_labels },
 spec={
 'type': 'LoadBalancer',
 'ports': [{ 'port': 80, 'targetPort': 80, 'protocol': 'TCP' }],
 'selector': app_labels,
 }
)
pulumi.export('appIp', app_svc.status.apply(lambda s: s.loadbalancer.ingress[0].ip))

package main

import (
 // [Previous imports...]
)

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 // [Registry, build, etc, code from above...]

 // Create a load balanced Kubernetes service using this image, and export its IP.
 appLabels := pulumi.StringMap{"app": pulumi.String("myapp")}
 _, deperr := appsv1.NewDeployment(ctx, "app-dep", &appsv1.DeploymentArgs{
 Metadata: &metav1.ObjectMetaArgs{Labels: appLabels},
 Spec: appsv1.DeploymentSpecArgs{
 Selector: &metav1.LabelSelectorArgs{MatchLabels: appLabels},
 Replicas: pulumi.Int(3),
 Template: &corev1.PodTemplateSpecArgs{
 Metadata: &metav1.ObjectMetaArgs{Labels: appLabels},
 Spec: &corev1.PodSpecArgs{
 Containers: corev1.ContainerArray{
 corev1.ContainerArgs{
 Name: pulumi.String("myapp"),
 Image: image.ImageName,
 },
 },
 },
 },
 },
 })
 if deperr != nil {
 return deperr
 }
 appSvc, svcerr := corev1.NewService(ctx, "app-svc", &corev1.ServiceArgs{
 Metadata: &metav1.ObjectMetaArgs{Labels: appLabels},
 Spec: &corev1.ServiceSpecArgs{
 Type: pulumi.String("LoadBalancer"),
 Ports: corev1.ServicePortArray{
 corev1.ServicePortArgs{Port: pulumi.Int(80)},
 },
 Selector: appLabels,
 },
 })
 if svcerr != nil {
 return svcerr
 }
 ctx.Export("appIp", appSvc.Status.ApplyT(func(status *corev1.ServiceStatus) *string {
 return status.LoadBalancer.Ingress[0].Ip
 }))

 return nil
 })
}

// [Previous imports...]
using Pulumi.Kubernetes.Types.Inputs.Core.V1;
using Pulumi.Kubernetes.Types.Inputs.Apps.V1;
using Pulumi.Kubernetes.Types.Inputs.Meta.V1;

class Program
{
 static Task<int> Main() => Deployment.RunAsync(async () => {
 // [Registry, build, etc, code from above...]

 // Create a load balanced Kubernetes service using this image, and export its IP.
 var appLabels = new InputMap<string>
 {
 { "app", "myapp" }
 };
 var appDep = new Pulumi.Kubernetes.Apps.V1.Deployment("app-dep", new DeploymentArgs
 {
 Spec = new DeploymentSpecArgs
 {
 Selector = new LabelSelectorArgs
 {
 MatchLabels = appLabels
 },
 Replicas = 3,
 Template = new PodTemplateSpecArgs
 {
 Metadata = new ObjectMetaArgs
 {
 Labels = appLabels,
 },
 Spec = new PodSpecArgs
 {
 Containers =
 {
 new Pulumi.Kubernetes.Types.Inputs.Core.V1.ContainerArgs
 {
 Name = "myapp",
 Image = image.ImageName,
 }
 }
 }
 }
 }
 });
 var appSvc = new Pulumi.Kubernetes.Core.V1.Service("app-svc", new Pulumi.Kubernetes.Types.Inputs.Core.V1.ServiceArgs
 {
 Metadata = new ObjectMetaArgs
 {
 Labels = appLabels
 },
 Spec = new ServiceSpecArgs
 {
 Type = "LoadBalancer",
 Ports =
 {
 new ServicePortArgs
 {
 Port = 80,
 TargetPort = 80
 }
 },
 Selector = appLabels
 }
 });

 return new Dictionary<string, object>
 {
 // [Previous exports...]
 { "appIp", appSvc.Status.Apply(status => status.LoadBalancer.Ingress[0].Ip) },
 };
 }
}

Notice here that we are referring to the resulting image name from our service specification. All we need to do run a ‘pulumi up’ and Pulumi will now build, publish, and consume our application’s container image from within our Kubernetes cluster:

$ pulumi up
Updating (dev)

 Type Name Status
 + pulumi:pulumi:Stack project-dev created
 ... prior output omitted ...
 + ├─ kubernetes:apps/v1:Deployment app-dep created
 + └─ kubernetes:core/v1:Service app-svc created

Outputs:
 appIp : "34.82.32.166"
 baseImageName: "...cloud-specific url.../my-repo-dc811b0"
 fullImageName: "...cloud-specific url.../my-repo-dc811b0:fcbbd958636e4f8ac02568db7dbf8b89a043e210e917432cf12649aaedfa266c"

If this is the first time you’ve run pulumi up, all of the prior resources will be provisioned first, and in any case, the Kubernetes resources will follow.

Now that our deployment has completed, we can curl the endpoint:

$ curl $(pulumi stack output appIp)
<h1>Hello, World -- from Pulumi!</h1>

This image name is the versioned one, meaning that any time a new version is created, Pulumi will detect that it needs to update the Kubernetes deployment which references it, triggering a rollout of the new deployed image. As such, we just need to run pulumi up anytime the application or its Dockerfile changes and Pulumi will detect and trigger a deployment to Kubernetes.

To see this in action, let’s change our Dockerfile’s contents once more:

FROM nginx
RUN echo "<h1>Hello, World -- from Pulumi and Kubernetes!</h1>" > \
 /usr/share/nginx/html/index.html

And then rerun Pulumi – notice that both the image and the Kubernetes deployment has changed this time:

$ pulumi up
Updating (dev)

 Type Name Status Info
 + pulumi:pulumi:Stack project-dev created
 ~ ├─ docker:image:Image my-image updated
 ~ └─ kubernetes:core/v1:Deployment app-dep updated [diff: ~spec]

Outputs:
 appIp : "34.82.32.166"
 baseImageName: "...cloud-specific url.../my-repo-dc811b0"
 fullImageName: "...cloud-specific url.../my-repo-dc811b0:36919b56f6b2dedfa879815443c9964d17a89506caed25025328b1d0204a083f"

Finally, if we re-curl the endpoint, we will now see that the updated container is now live!

$ curl $(pulumi stack output appIp)
<h1>Hello, World -- from Pulumi and Kubernetes!</h1>

And there we go: we have gone from a Dockerfile to a published container image in a container registry of our choosing, which has been used to spin up a load balanced Kubernetes service, and which is now ready for fully automated continuous deployments.

Wrapping Up

In this article, we’ve seen how easy it is to build, publish, and use container images in many popular public and private container registry options. We have seen how to provision new registries using infrastructure as code and how easy it is to trigger deployments of application updates by running a single pulumi up command.

All of these steps were manually run from a CLI; however, a natural next step is to wire the entire process up to a CI/CD system such as GitHub Actions, GitLab Pipelines, Jenkins, Spinnaker, or one of the many available options, so that you can deploy continuously as you merge code. For even more advanced scenarios, we might want to build a custom program such as a CLI that uses the Automation API to perform these actions behind a simpler, purpose-built interface.

Although we’ve shown a very simple set of infrastructure resources, it would be natural to extend these examples by provisioning other ancillary services that your application needs, including databases, pub/sub topics, queues, metrics and dashboards, and more. Using an infrastructure as code approach to building, publishing, and consuming your container images means you can incrementally add on such infrastructure to the base code shown above and reference them from your containers easily with automatic dependency tracking.

The complete examples in this article are available on GitHub. Pulumi is open source and free to get started with — give it a try, and get up and running with infrastructure as code for your containers today!

Switching the application stack from PERN to MERN

Vova Ivanov — Fri, 18 Sep 2020 00:00:00 +0000

This post is outdated and contains references to a pre-release version of Pulumi Crosswalk (@pulumi/awsx). For updated AWSx documentation and examples, see the AWS Guides.

In this blog post, we return to the PERN application we previously migrated to Kubernetes and replace the PostgreSQL database with MongoDB. Although it might seem like a difficult task initially, the straightforward design of Pulumi and Kubernetes allows us to easily transition the application form a PERN stack to a MERN one.

The main difference between PostgreSQL and MongoDB is data is stored. PostgreSQL is a relational database that allows users to create complex tables and relations between values. In contrast, MongoDB is a key-value database that stores data in simple collections instead of a relational model. Because the application takes the form of three distinct components–the client, server, and database–almost all of the changes will occur in the database component. In fact, we can reuse most of the existing code and will be able to change the database without additional hassle.

The first step to switching the stack is to clone the PERN Kubernetes example. We’ll use a sparse clone to copy only the aws-ts-k8s-voting-app directory.

$ mkdir examples && cd examples
$ git init
$ git remote add origin -f https://github.com/pulumi/examples/
$ git config core.sparseCheckout true
$ echo aws-ts-k8s-voting-app >> .git/info/sparse-checkout
$ git pull origin master

The next step is to create a new directory and initialize a Pulumi project with pulumi new aws-typescript.

$ mkdir aws-ts-k8s-mern-voting-app && cd aws-ts-k8s-mern-voting-app
$ pulumi new aws-typescript

The project will require several configuration variables, which we set using pulumi config set. The variables are used to configure the MongoDB user account, initializing the database schema and table, and its region.

$ pulumi config set sql-user-name <NAME>
$ pulumi config set sql-user-password <PASSWORD> --secret
$ pulumi config set aws:region <REGION>

The package.json file lists the libraries used by the project. We will add the following to the dependencies section:

 "@pulumi/eks": "^0.20.0",
 "@pulumi/cloud-aws": "^0.19.0"

As most of our project components are nearly identical to those in the PERN Kubernetes application, we can copy many of them into our directory.

$ cd ..
$ cp -r aws-ts-k8s-voting-app/clientside/ aws-ts-k8s-mern-voting-app/clientside
$ cp -r aws-ts-k8s-voting-app/serverside/ aws-ts-k8s-mern-voting-app/serverside
$ cp -r aws-ts-k8s-voting-app/databaseside/ aws-ts-k8s-mern-voting-app/databaseside

$ cd aws-ts-k8s-voting-app

Hosting MongoDB will require a rework of the database Docker container and startup scripts. Like before, the outer databaseside folder holds our Dockerfile, while the inner database folder contains code.

FROM ubuntu:18.04

WORKDIR /

EXPOSE 5432

RUN apt update && \
 apt install -y mongodb

ADD database /database

CMD [ "/database/startDatabase.sh" ]

Our setup doesn’t require any files, and so the only thing we need to put in the database folder is a startDatabase.sh script that launches the database, configures users, and creates a table.

#!/bin/bash
set -exu
FILE=/persistentVolume/mongod.lock

if test -f "$FILE"; then
 echo "/persistentVolume already contains MongoDB, no need to initialize database."
 mongod --fork --dbpath /persistentVolume/ --bind_ip_all --logpath /persistentVolume/mongoLogs
else
 echo "/persistentVolume is empty, and we need to initialize the MongoDB database."
 mongod --fork --dbpath /persistentVolume/ --bind_ip_all --logpath /persistentVolume/mongoLogs
 echo "use $DATABASE_NAME
 db.choices.insert({ _id: 0, text: \"Tabs\", vote_count: 0 })
 db.choices.insert({ _id: 1, text: \"Spaces\", vote_count: 0 })
 db.createUser(
 {
 user: \"$USER_NAME\",
 pwd: \"$USER_PASSWORD\",
 roles: [ { role: \"readWrite\", db: \"$DATABASE_NAME\" } ]
 }
 )" | mongo
fi

while true; do
 sleep 3600
done

With the database in place, all that is left is to make some small MongoDB-specific changes to how the client and server components send queries.

The server component will be changed to use a model.js file, which acts as a blueprint for the database’s choices.

const mongoose = require("mongoose");

let Choice = new mongoose.Schema({
 _id: Number,
 text: {
 type: String
 },
 vote_count: {
 type: Number
 },
});

module.exports = mongoose.model("choice", Choice);

Likewise, the db.js file will be modified to create a specialized to our database.

const mongoose = require("mongoose");

const url = "mongodb://"
 + process.env["MONGODB_ADDRESS"]
 + ":" + process.env["MONGODB_PORT"]
 + "/" + process.env["DATABASE_NAME"]

mongoose.connect(url, {
 useNewUrlParser: true,
 user: process.env["USER_NAME"],
 pass: process.env["USER_PASSWORD"]
});

const connection = mongoose.connection;
module.exports = connection;

And finally, the index.js file holding the main code of our server will be modified to send queries to the MongoDB database.

const express = require("express");
const app = express();
const cors = require("cors");
const connection = require("./db");

app.use(cors());
app.use(express.json());

connection.once("open", function() {
 console.log("Connection opened to database!");
})

let Choice = require("./model");

app.get("/voting", async (request, response) => {
 console.log("Get all request");
 Choice.find(function(error, result) {
 if (error) {
 console.log(error);
 } else {
 response.json(result);
 }
 });
});

app.post("/voting/:id", async (request, response) => {
 const { id } = request.params;
 console.log("Casting vote for: " + id);

 Choice.findById(id, function(error, result) {
 if (!result) {
 response.status(404).send("Choice not found");
 } else {
 result.vote_count = result.vote_count + 1;
 result.save().then(result => {
 response.json("Vote successfully cast");
 }).catch(error => {
 response.status(400).send("Failed to cast vote");
 });
 }
 });
});

app.listen(5000, async () => {
 console.log("server has started on port 5000");
});

The VotingComponent.js file in the client will be slightly modified to reference choices by their MongoDB _id parameter.

import React, { Fragment, useEffect, useState } from "react";
const fullServerUrl = "http://" + window.SERVER_URL + ":5000/voting";

const ListChoices = () => {
 const [choices, setChoices] = useState([]);

 const getChoices = async () => {...};

 useEffect(() => {...}, []);

 return (
 <Fragment>
 <h1 className="text-center mt-5">Pulumi Voting App</h1>
 {" "}
 <table className="table mt-5 text-center">
 <thead>
 <tr>
 <th>Choice</th>
 <th>Votes</th>
 </tr>
 </thead>
 <tbody>
 {choices.map(choice => (
 <tr key={choice._id}>
 <td>{choice.text}</td>
 <td>{choice.vote_count}</td>
 <td>
 <button
 className="btn btn-success"
 onClick={() => castVote(choice._id)}
 >
 Vote
 </button>
 </td>
 </tr>
 ))}
 </tbody>
 </table>
 </Fragment>
 );
};

async function castVote(id) {...}

export default ListChoices;

Now that, server, client, and database have been fully converted to use MongoDB, we can make the last remaining change in the infrastructure by updating the database deployment and service.

import * as aws from "@pulumi/aws";
import * as awsx from "@pulumi/awsx";
import * as eks from "@pulumi/eks";
import * as k8s from "@pulumi/kubernetes";
import * as pulumi from "@pulumi/pulumi";

const config = new pulumi.Config();
const sqlUserName = config.require("sql-user-name");
const sqlUserPassword = config.requireSecret("sql-user-password");
const region = aws.config.region;

const eksCluster = new eks.Cluster(...);

const ebsVolume = new aws.ebs.Volume(...);

const databaseAppName = "database-side-service";
const databaseAppLabels = { appClass: databaseAppName };
const databaseDeployment = new k8s.apps.v1.Deployment(databaseAppName, {
 metadata: { name: databaseAppName, labels: databaseAppLabels },
 spec: {
 replicas: 1,
 selector: { matchLabels: databaseAppLabels },
 template: {
 metadata: { labels: databaseAppLabels },
 spec: {
 containers: [{
 name: databaseAppName,
 image: awsx.ecr.buildAndPushImage("database-side-service", "./databaseside").image(),
 ports: [{ name: "http", containerPort: 27017 }],
 env: [
 { name: "DATABASE_NAME", value: databaseName },
 { name: "USER_NAME", value: sqlUserName },
 { name: "USER_PASSWORD", value: sqlUserPassword },

 ],
 volumeMounts: [{
 name: "persistent-volume",
 mountPath: "/persistentVolume"
 }],
 resources: {
 limits: {
 memory: "1Gi",
 cpu: "1000m"
 }
 }
 }],
 volumes: [{
 name: "persistent-volume",
 awsElasticBlockStore: {
 volumeID: ebsVolume.id,
 },
 }],
 affinity: {
 nodeAffinity: {
 requiredDuringSchedulingIgnoredDuringExecution: {
 nodeSelectorTerms: [{
 matchExpressions: [{
 key: "failure-domain.beta.kubernetes.io/zone",
 operator: "In",
 values: [ebsVolume.availabilityZone],
 }]
 }]
 }
 }
 }
 }
 },
 strategy: {
 type: "Recreate"
 }
 }}, {
 deleteBeforeReplace: true,
 provider: eksCluster.provider,
});

const databasesideListener = new k8s.core.v1.Service("database-side-listener", {
 metadata: { labels: databaseDeployment.metadata.labels },
 spec: {
 type: "ClusterIP",
 ports: [{ port: 27017, targetPort: "http" }],
 selector: databaseAppLabels,
 publishNotReadyAddresses: false,
 }}, {
 provider: eksCluster.provider,
 }
);

const mongodbAddress = databasesideListener.spec.clusterIP;

const serverAppName = "server";
const serverAppLabels = { appClass: serverAppName };
const serverDeployment = new k8s.apps.v1.Deployment("server-side-service", {
 metadata: { labels: serverAppLabels },
 spec: {
 replicas: 2,
 selector: { matchLabels: serverAppLabels },
 template: {
 metadata: { labels: serverAppLabels },
 spec: {
 containers: [{
 name: serverAppName,
 image: awsx.ecr.buildAndPushImage("server-side-service", "./serverside").image(),
 ports: [{ name: "http", containerPort: 5000 }],
 env: [
 { name: "USER_NAME", value: sqlUserName },
 { name: "USER_PASSWORD", value: sqlUserPassword },
 { name: "MONGODB_ADDRESS", value: mongodbAddress },
 { name: "MONGODB_PORT", value: String(27017) },
 { name: "DATABASE_NAME", value: databaseName },
 ],
 resources: {
 limits: {
 memory: "500Mi",
 cpu: "500m"
 }
 }
 }],
 }
 }
 }}, {
 provider: eksCluster.provider,
});

const serversideListener = new k8s.core.v1.Service(...);

const clientAppName = ...;
const clientAppLabels = { ... };
const clientDeployment = new k8s.apps.v1.Deployment(...);

const clientsideListener = new k8s.core.v1.Service(...);

To give us a simple way to connect to our application, we export the clientside listener’s address. We can now open a browser window with the URL and port number to view our application.

export const kubeConfig = eksCluster.kubeconfig;
export const URL = clientsideListener.status.loadBalancer.ingress[0].hostname;

In this example, we showed how to change a PERN stack-based application to use MERN, and demonstrated the ease with which a designer can swap out different components. The isolated nature of containerized applications allows for a great deal of modularity. It can significantly reduce the amount of time spent renovating previously written code to fit any added new components.

The MERN application code is on Github.

Migrating a cloud application to Kubernetes

Vova Ivanov — Mon, 14 Sep 2020 00:00:00 +0000

This post is outdated and contains references to a pre-release version of Pulumi Crosswalk (@pulumi/awsx). For updated AWSx documentation and examples, see the AWS Guides.

In this blog post, we will explore and demonstrate the advantages of Kubernetes by converting and deploying our PERN application to Amazon EKS. With the help of Pulumi, the process becomes greatly simplified and allows us to focus more on the big picture of designing our cloud architecture.

Kubernetes offers several distinct advantages over individually deploying Docker containers to the cloud. Firstly, it’s a robust system for minimizing downtime and rolling out updates. If a pod or node is shut down, a new one is automatically allocated to take its place. Secondly, Kubernetes can scale and distribute your infrastructure. By placing containers into pods, Kubernetes allows you to design the right cloud setup to fit your target effortlessly. And lastly, Kubernetes runs on many cloud providers, letting you choose your organization’s best cloud service provider. Since AWS, Azure, and GCP all support deploying Kubernetes, you have the option of switching if the need arises.

The first step to creating the app is to clone the Typescript PERN example. We’ll use a sparse clone to copy only the aws-ts-pern-voting-app directory.

$ mkdir examples && cd examples
$ git init
$ git remote add origin -f https://github.com/pulumi/examples/
$ git config core.sparseCheckout true
$ echo aws-ts-pern-voting-app >> .git/info/sparse-checkout
$ git pull origin master

The next step is to create a new directory and initialize a Pulumi project with pulumi new aws-typescript.

$ mkdir aws-ts-k8s-voting-app && cd aws-ts-k8s-voting-app
$ pulumi new aws-typescript

The project will require several configuration variables, which we set using pulumi config set. The variables are used to configure the PostgreSQL admin account, a user account for initializing the schema and table, and its region.

$ pulumi config set sql-admin-name <NAME>
$ pulumi config set sql-admin-password <PASSWORD> --secret
$ pulumi config set sql-user-name <NAME>
$ pulumi config set sql-user-password <PASSWORD> --secret
$ pulumi config set aws:region <REGION>

The package.json file lists the libraries used by the project. We will add the following to the dependencies section:

"@pulumi/eks": "^0.20.0",
"@pulumi/cloud-aws": "^0.19.0"

Some of the components of our Kubernetes project are nearly identical to those in the PERN application. We can copy many of these files from the example into our directory.

$ cd ..
$ cp -r aws-ts-pern-voting-app/clientside/ aws-ts-k8s-voting-app/clientside
$ cp -r aws-ts-pern-voting-app/serverside/ aws-ts-k8s-voting-app/serverside
$ cd aws-ts-k8s-voting-app

To prepare our application for Kubernetes, we create a PostgreSQL Docker container for the application. Although this is slightly more complex than directly asking AWS to provision an RDS instance, the underlying mechanics are the same for either approach.

The first step is to create two directories:

$ mkdir databaseside && cd databaseside
$ mkdir database

Like the PERN app, the outer databaseside folder holds our Dockerfile, while the inner database folder contains code.

FROM ubuntu:18.04

WORKDIR /

EXPOSE 5432

RUN apt update && \
 apt install -y postgresql

ADD database /database

CMD [ "/database/startDatabase.sh" ]

Our setup doesn’t require any files, and so the only thing we need to put in the database folder is a startDatabase.sh script that launches the database, configures users, and creates a table.

#!/bin/bash
set -exu
FILE=/persistentVolume/postgresqlDb/postgresql.conf
chown postgres:postgres /persistentVolume

if test -f "$FILE"; then
 echo "/persistentVolume already contains postgresqlDb, no need to initialize database."
else
 echo "/persistentVolume is empty, and we need to initialize the postgresql database."
 cd /persistentVolume
 su postgres -c "/usr/lib/postgresql/10/bin/initdb -D /persistentVolume/postgresqlDb"

 echo "host all all 0.0.0.0/0 md5" >> /persistentVolume/postgresqlDb/pg_hba.conf
 echo "host all all ::/0 md5" >> /persistentVolume/postgresqlDb/pg_hba.conf
 echo "listen_addresses='*'" >> /persistentVolume/postgresqlDb/postgresql.conf

 su postgres -c "/usr/lib/postgresql/10/bin/pg_ctl -D /persistentVolume/postgresqlDb --wait -l logfile start"

 set +x
 echo "psql -U postgres -c \"CREATE ROLE $ADMIN_NAME LOGIN SUPERUSER PASSWORD *********;\""
 psql -U postgres -c "CREATE ROLE $ADMIN_NAME LOGIN SUPERUSER PASSWORD '$ADMIN_PASSWORD';"
 echo "psql -U postgres -c \"CREATE USER $USER_NAME WITH PASSWORD *********;\""
 psql -U postgres -c "CREATE USER $USER_NAME WITH PASSWORD '$USER_PASSWORD';"
 echo "psql -U postgres -c \"ALTER ROLE postgres WITH NOLOGIN;\""
 psql -U postgres -c "ALTER ROLE postgres WITH NOLOGIN;"
 set -x

 psql -U $ADMIN_NAME -d postgres -c "CREATE DATABASE $DATABASE_NAME;"
 psql -U $ADMIN_NAME -d $DATABASE_NAME -c "
 CREATE SCHEMA voting_app;
 CREATE TABLE voting_app.choice(
 choice_id SERIAL PRIMARY KEY,
 text VARCHAR(255) NOT NULL,
 vote_count INTEGER NOT NULL
 );
 GRANT USAGE ON SCHEMA voting_app TO $USER_NAME;
 GRANT SELECT, UPDATE ON ALL TABLES IN SCHEMA voting_app TO $USER_NAME;
 INSERT INTO voting_app.choice (text, vote_count) VALUES('Tabs', 0);
 INSERT INTO voting_app.choice (text, vote_count) VALUES('Spaces', 0);
 "
 su postgres -c "/usr/lib/postgresql/10/bin/pg_ctl -D /persistentVolume/postgresqlDb --wait -l logfile stop"
fi

su postgres -c "/usr/lib/postgresql/10/bin/postgres -D /persistentVolume/postgresqlDb"

Because we don’t have any SSL certificates to authenticate and encrypt internet traffic, the way the server connects to the database needs to be modified to include an ssl: false pool parameter.

const Pool = require("pg").Pool;

const pool = new Pool({
 user: process.env["USER_NAME"],
 password: process.env["USER_PASSWORD"],
 host: process.env["POSTGRES_ADDRESS"],
 port: process.env["POSTGRES_PORT"],
 database: process.env["DATABASE_NAME"],
 ssl: false,
});

module.exports = pool;

With our server, client, and database in place, we can focus on the infrastructure. We start with importing libraries and describing the application’s configuration options.

import * as aws from "@pulumi/aws";
import * as awsx from "@pulumi/awsx";
import * as eks from "@pulumi/eks";
import * as k8s from "@pulumi/kubernetes";
import * as pulumi from "@pulumi/pulumi";

const config = new pulumi.Config();
const sqlAdminName = config.require("sql-admin-name");
const sqlAdminPassword = config.requireSecret("sql-admin-password");
const sqlUserName = config.require("sql-user-name");
const sqlUserPassword = config.requireSecret("sql-user-password");
const awsConfig = new pulumi.Config("aws");
const region = aws.config.region;

The central part of our application is an AWS Elastic Kubernetes Cluster. It holds our application and dictates how many nodes should be allocated for the processes running inside the cluster.

const eksCluster = new eks.Cluster("eksCluster", {
 name: "eksCluster",
 instanceType: "t2.medium",
 desiredCapacity: 3,
 minSize: 2,
 maxSize: 4,
 deployDashboard: false,
 enabledClusterLogTypes: [
 "api",
 "audit",
 "authenticator",
 ],
});

Kubernetes nodes use ephemeral storage. When Pods shut down or get restarted, everything is erased. To create a permanent storage system suitable for our database, we need a Persistent Volume instance.

const ebsVolume = new aws.ebs.Volume("storage-volume", {
 size: 1,
 type: "gp2",
 availabilityZone: region + "a",
 encrypted: true,
 }, {
 protect: false,
});

Now that the infrastructure for our database is ready, we can launch a PostgreSQL server on the cloud in the form of a Deployment. Deployments offer a multitude of customization options ranging from attaching volumes, setting the memory and cpu requirements, to specifying which deployments can and cannot be run on the same node.

const databaseAppName = "database-side-service";
const databaseAppLabels = { appClass: databaseAppName };
const databaseDeployment = new k8s.apps.v1.Deployment(databaseAppName, {
 metadata: { name: databaseAppName, labels: databaseAppLabels },
 spec: {
 replicas: 1,
 selector: { matchLabels: databaseAppLabels },
 template: {
 metadata: { labels: databaseAppLabels },
 spec: {
 containers: [{
 name: databaseAppName,
 image: awsx.ecr.buildAndPushImage("database-side-service", "./databaseside").image(),
 ports: [{ name: "http", containerPort: 5432 }],
 env: [
 { name: "ADMIN_NAME", value: sqlAdminName },
 { name: "ADMIN_PASSWORD", value: sqlAdminPassword },
 ],
 volumeMounts: [{
 name: "persistent-volume",
 mountPath: "/persistentVolume"
 }],
 resources: {
 limits: {
 memory: "1Gi",
 cpu: "1000m"
 }
 }
 }],
 volumes: [{
 name: "persistent-volume",
 awsElasticBlockStore: {
 volumeID: ebsVolume.id,
 },
 }],
 affinity: {
 nodeAffinity: {
 requiredDuringSchedulingIgnoredDuringExecution: {
 nodeSelectorTerms: [{
 matchExpressions: [{
 key: "failure-domain.beta.kubernetes.io/zone",
 operator: "In",
 values: [ebsVolume.availabilityZone],
 }]
 }]
 }
 }
 }
 }
 },
 strategy: {
 type: "Recreate"
 }
 }}, {
 deleteBeforeReplace: true,
 provider: eksCluster.provider,
});

In order to have a a way for the pods in cluster to communicate with our database, we create a Kubernetes service for it. It is best practice to keep databases and other similar components entirely within the cluster, and not allow them to be accessed directly the internet.

const databasesideListener = new k8s.core.v1.Service("database-side-listener", {
 metadata: { labels: databaseDeployment.metadata.labels },
 spec: {
 type: "ClusterIP",
 ports: [{ port: 5432, targetPort: "http" }],
 selector: databaseAppLabels,
 publishNotReadyAddresses: false,
 }}, {
 provider: eksCluster.provider,
 }
);

const postgresqlAddress = databasesideListener.spec.clusterIP;
});

Now, all that remains is deploying the client and server containers to Kubernetes. Since the PERN application already deployed them as docker containers, it doesn’t take much effort to reconfigure it for Kubernetes. Unlike the database, these components can safely be open to the Internet using a service with a Load Balancer type.

We’ll first set up the server deployment:

const serverAppName = "server";
const serverAppLabels = { appClass: serverAppName };
const serverDeployment = new k8s.apps.v1.Deployment("server-side-service", {
 metadata: { labels: serverAppLabels },
 spec: {
 replicas: 2,
 selector: { matchLabels: serverAppLabels },
 template: {
 metadata: { labels: serverAppLabels },
 spec: {
 containers: [{
 name: serverAppName,
 image: awsx.ecr.buildAndPushImage("server-side-service", "./serverside").image(),
 ports: [{ name: "http", containerPort: 5000 }],
 env: [
 { name: "USER_NAME", value: sqlUserName },
 { name: "USER_PASSWORD", value: sqlUserPassword },
 { name: "POSTGRES_ADDRESS", value: postgresqlAddress },
 { name: "POSTGRES_PORT", value: String(5432) },
 { name: "DATABASE_NAME", value: postgresDatabase.name },
 ],
 resources: {
 limits: {
 memory: "500Mi",
 cpu: "500m"
 }
 }
 }],
 }
 }
 }}, {
 provider: eksCluster.provider,
});

const serversideListener = new k8s.core.v1.Service("server-side-listener", {
 metadata: { labels: serverDeployment.metadata.labels },
 spec: {
 type: "LoadBalancer",
 ports: [{ port: 5000, targetPort: "http" }],
 selector: serverAppLabels,
 publishNotReadyAddresses: false,
 }}, {
 provider: eksCluster.provider,
 }
);

And lastly, the client deployment.

const clientAppName = "client";
const clientAppLabels = { appClass: clientAppName };
const clientDeployment = new k8s.apps.v1.Deployment("client-side-service", {
 metadata: { labels: clientAppLabels },
 spec: {
 replicas: 2,
 selector: { matchLabels: clientAppLabels },
 template: {
 metadata: { labels: clientAppLabels },
 spec: {
 containers: [{
 name: clientAppName,
 image: awsx.ecr.buildAndPushImage("client-side-service", "./clientside").image(),
 ports: [{ name: "http", containerPort: 3000 }],
 env: [
 { name: "SERVER_HOSTNAME", value: serversideListener.status.loadBalancer.ingress[0].hostname },
 ],
 resources: {
 limits: {
 memory: "500Mi",
 cpu: "500m"
 }
 },
 }],
 }
 }
 }}, {
 provider: eksCluster.provider,
});

const clientsideListener = new k8s.core.v1.Service("client-side-listener", {
 metadata: { labels: clientDeployment.metadata.labels },
 spec: {
 type: "LoadBalancer",
 ports: [{ port: 3000, targetPort: "http" }],
 selector: clientAppLabels,
 publishNotReadyAddresses: false,
 }}, {
 provider: eksCluster.provider,
 }
);

To give us a simple way to connect to our application, we export the clientside listener’s address. We can now open a browser window with the URL and port number to view our application.

export const kubeConfig = eksCluster.kubeconfig;
export const URL = clientsideListener.status.loadBalancer.ingress[0].hostname;

In this example, we demonstrated the benefits Kubernetes offers and showed how to use Pulumi to deploy an application to Kubernetes hosted on AWS. Although it might seem unnecessary to use such a system for only a single voting app, the advantages of running your project in the form of containerized services become apparent as your application grows in size.

Next week, we’ll explore applications using the MERN stack: MongoDB, Express, React, and NodeJS.

The blog post’s code can be found on Github.

Deploying a PERN stack application to AWS

Vova Ivanov — Fri, 04 Sep 2020 00:00:00 +0000

Some of the code in this post is out of date. See the AWS guides for an updated overview and examples.

In this blog post, we will explore PERN stack applications and deploy one to AWS. PERN is an acronym for PostgreSQL, Express, React, and Node. A PERN stack application is a project that uses PostgreSQL, Express as an application framework, React as a user interface framework, and runs on Node. We will also use Pulumi Crosswalk to reduce the amount of code and provide a quick and straightforward path for deploying the application.

PERN projects have four distinct tiers:

a database that keeps track of our data,
a stateless server that receives commands to manage the database,
a clientside server that contains and renders the user interface code,
and the users who run the code in their browsers and send requests to the stateless server.

An advantage of infrastructure as code is that the application and infrastructure deployment can use the same language. As React and the other components use NodeJS, we’ll use it for our infrastructure by writing it in TypeScript. The first step is to create a new directory and initialize a Pulumi project with pulumi new aws-typescript.

$ mkdir aws-ts-pern-voting-app && cd aws-ts-pern-voting-app
$ pulumi new aws-typescript

This tutorial was written for the aws-ts-pern-voting-app example but will work with any other PERN stack application. The example uses two folders to hold the client and server tiers and a Dockerfile that builds images that run as containers in AWS.

To deploy our PERN stack, the project requires several configuration variables, which we set using pulumi config set. The variables are used to configure the PostgreSQL admin account, a user account for initializing the schema and table, and the database’s region.

$ pulumi config set sql-admin-name <NAME>
$ pulumi config set sql-admin-password <PASSWORD> --secret
$ pulumi config set sql-user-name <NAME>
$ pulumi config set sql-user-password <PASSWORD> --secret
$ pulumi config set aws:region <REGION>

The package.json file lists the libraries used by the project. We will add the following to the dependencies section:

"@pulumi/cloud-aws": "^0.19.0",
"@pulumi/postgresql": "^2.3.0",
"pg": "^8.3.3"

Our project uses a Dynamic Provider to help create tables and Schemas. It offers the same features as our MySQL provider, but for PostgreSQL.

import * as pulumi from "@pulumi/pulumi";
import * as crypto from "crypto";

export interface SchemaInputs {
 creatorName: pulumi.Input<string>
 creatorPassword: pulumi.Input<string>
 serverAddress: pulumi.Input<string>
 databaseName: pulumi.Input<string>
 creationScript: pulumi.Input<string>
 deletionScript: pulumi.Input<string>
 postgresUserName: pulumi.Input<string>
}

export class SchemaProvider implements pulumi.dynamic.ResourceProvider {
 async create(args: SchemaInputs): Promise<pulumi.dynamic.CreateResult> {
 const { Pool } = require("pg");
 const pool = new Pool({
 user: args.creatorName,
 password: args.creatorPassword,
 host: args.serverAddress,
 port: 2000,
 database: args.databaseName
 });
 const scriptExecuted = await pool.query(args.creationScript);

 await pool.end();
 return {id: "postgresqlSchema-" + crypto.randomBytes(16).toString('hex'), outs: args};
 }

 async delete(id: string, args: SchemaInputs): Promise<void> {
 const { Pool } = require("pg");
 const pool = new Pool({
 user: args.creatorName,
 password: args.creatorPassword,
 host: args.serverAddress,
 port: 2000,
 database: args.databaseName
 });
 const scriptExecuted = await pool.query(args.deletionScript);
 await pool.end();
 }

 async diff(id: string, oldArgs: SchemaInputs, newArgs: SchemaInputs): Promise<pulumi.dynamic.DiffResult> {
 let changes: boolean = ((oldArgs.creatorName != newArgs.creatorName) ||
 (oldArgs.creatorPassword != newArgs.creatorPassword) || (oldArgs.serverAddress != newArgs.serverAddress) ||
 (oldArgs.databaseName != newArgs.databaseName) || (oldArgs.creationScript != newArgs.creationScript) ||
 (oldArgs.deletionScript != newArgs.deletionScript));

 let replaces: string[] = [];
 if (oldArgs.serverAddress != newArgs.serverAddress) { replaces.push("serverAddress") };
 if (oldArgs.databaseName != newArgs.databaseName) { replaces.push("databaseName") };
 if (oldArgs.creationScript != newArgs.creationScript) { replaces.push("creationScript") };

 return {
 changes: changes,
 replaces: replaces,
 stables: [],
 deleteBeforeReplace: true
 }
 }

 async update(id: string, oldArgs: SchemaInputs, newArgs: SchemaInputs): Promise<pulumi.dynamic.UpdateResult> {
 return { outs: newArgs };
 }
}

export class Schema extends pulumi.dynamic.Resource {
 public readonly creatorName!: pulumi.Output<string>;
 public readonly creatorPassword!: pulumi.Output<string>;
 public readonly serverAddress!: pulumi.Output<string>;
 public readonly databaseName!: pulumi.Output<string>;
 public readonly creationScript!: pulumi.Output<string>;
 public readonly deletionScript!: pulumi.Output<string>;
 constructor(name: string, args: SchemaInputs) {
 super(new SchemaProvider, name, args);
 }
}

With the Dynamic provider configured, we can focus on the main index.ts file. We start with importing libraries and describing the application’s configuration options.

import * as aws from "@pulumi/aws";
import * as awsx from "@pulumi/awsx";
import * as pulumi from "@pulumi/pulumi";
import * as postgresql from "@pulumi/postgresql";
import { Schema } from "./PostgreSqlDynamicProvider";
import { table } from "console";

const config = new pulumi.Config();
const sql_admin_name = config.require("sql-admin-name");
const sql_admin_password = config.requireSecret("sql-admin-password");
const sql_user_name = config.require("sql-user-name");
const sql_user_password = config.requireSecret("sql-user-password");
const awsConfig = new pulumi.Config("aws");
const availabilityZone = awsConfig.get("region");

Apart from language differences, the code for creating the VPC, subnets, and tables is almost identical to our previous projects. Since we will be using Crosswalk, we can leave out a few components that will be automatically created later.

const appVpc = new aws.ec2.Vpc("app-vpc", {
 cidrBlock: "172.31.0.0/16",
 enableDnsHostnames: true
});

const appGateway = new aws.ec2.InternetGateway("app-gateway", {
 vpcId: appVpc.id
});

const appRoutetable = new aws.ec2.RouteTable("app-routetable", {
 routes: [
 {
 cidrBlock: "0.0.0.0/0",
 gatewayId: appGateway.id,
 }
 ],
 vpcId: appVpc.id
});

const appRoutetableAssociation = new aws.ec2.MainRouteTableAssociation("app-routetable-association", {
 routeTableId: appRoutetable.id,
 vpcId: appVpc.id
});

const rdsSecurityGroup = new aws.ec2.SecurityGroup("rds-security-group", {
 vpcId: appVpc.id,
 description: "Enables HTTP access",
 ingress: [{
 protocol: 'tcp',
 fromPort: 0,
 toPort: 65535,
 cidrBlocks: ['0.0.0.0/0'],
 }],
 egress: [{
 protocol: '-1',
 fromPort: 0,
 toPort: 0,
 cidrBlocks: ['0.0.0.0/0'],
 }]
});

const firstRdsSubnet = new aws.ec2.Subnet("first-rds-subnet", {
 vpcId: appVpc.id,
 cidrBlock: "172.31.0.0/20",
 availabilityZone: availabilityZone + "a"
});

const secondRdsSubnet = new aws.ec2.Subnet("second-rds-subnet", {
 vpcId: appVpc.id,
 cidrBlock: "172.31.128.0/20",
 availabilityZone: availabilityZone + "b"
});

We create a SubnetGroup and an RDS instance. The latter uses PostgreSQL instead of MySQL, and is assigned 2000.

const rdsSubnetGroup = new aws.rds.SubnetGroup("rds-subnet-group", {
 subnetIds: [firstRdsSubnet.id, secondRdsSubnet.id]
});

const postgresqlRdsServer = new aws.rds.Instance("postgresql-rds-server", {
 engine: "postgres",
 username: sql_admin_name,
 password: sql_admin_password,
 instanceClass: "db.t2.micro",
 allocatedStorage: 20,
 skipFinalSnapshot: true,
 publiclyAccessible: true,
 port: 2000,
 dbSubnetGroupName: rdsSubnetGroup.name,
 vpcSecurityGroupIds: [rdsSecurityGroup.id]
});

Pulumi offers additional tools to make handling PostgreSQL easier.

const postgresqlProvider = new postgresql.Provider("postgresql-provider", {
 host: postgresqlRdsServer.address,
 port: postgresqlRdsServer.port,
 username: sql_admin_name,
 password: sql_admin_password,
 superuser: false
});

We initialize the example database and create a user to manage it.

const postgresDatabase = new postgresql.Database("postgresql-database", {
 name: "votes"}, {
 provider: postgresqlProvider
});

const postgresUser = new postgresql.Role("postgres-standard-role", {
 name: sql_user_name,
 password: sql_user_password,
 superuser: false,
 login: true,
 connectionLimit: -1}, {
 provider: postgresqlProvider
});

We use the Dynamic provider to create a schema and a table, grant permissions for our user to edit and select it, and populate the table with two initial voting options.

const creation_script = `
 CREATE SCHEMA voting_app;
 CREATE TABLE voting_app.choice(
 choice_id SERIAL PRIMARY KEY,
 text VARCHAR(255) NOT NULL,
 vote_count INTEGER NOT NULL
 );
 GRANT USAGE ON SCHEMA voting_app TO ${sql_user_name};
 GRANT SELECT, UPDATE ON ALL TABLES IN SCHEMA voting_app TO ${sql_user_name};
 INSERT INTO voting_app.choice (text, vote_count) VALUES('Tabs', 0);
 INSERT INTO voting_app.choice (text, vote_count) VALUES('Spaces', 0);
`;

const deletion_script = "DROP SCHEMA IF EXISTS voting_app CASCADE";

const postgresqlVotesTable = new Schema("postgresql-votes-schema", {
 creatorName: sql_admin_name,
 creatorPassword: sql_admin_password,
 serverAddress: postgresqlRdsServer.address,
 databaseName: postgresDatabase.name,
 creationScript: creation_script,
 deletionScript: deletion_script,
 postgresUserName: postgresUser.name
});

With the basic infrastructure and provider completed, we can write the application deployment code to ECS. We will use Pulumi Crosswalk, a collection of libraries that makes common infrastructure-as-code tasks in AWS easier and more secure by automatically using well-architected best practices.

We’ll first set up the server. The Network Listener is assigned the same port as the server, which is, in our case, port 5000. A set of environment variables representing our PostgreSQL connection credentials are passed directly to the awsx.ecs.FargateService. With AWS Crosswalk, what would have been over 150 lines of code is reduced to just under 20 lines of code.

const serversideListener = new awsx.elasticloadbalancingv2.NetworkListener("server-side-listener", { port: 5000 });
const serversideService = new awsx.ecs.FargateService("server-side-service", {
 taskDefinitionArgs: {
 containers: {
 serversideService: {
 image: awsx.ecs.Image.fromPath("server-side-service", "./serverside"),
 memory: 512,
 portMappings: [serversideListener],
 environment: [
 { name: "USER_NAME", value: sql_user_name },
 { name: "USER_PASSWORD", value: sql_user_password },
 { name: "RDS_ADDRESS", value: postgresqlRdsServer.address },
 { name: "RDS_PORT", value: String(2000) },
 { name: "DATABASE_NAME", value: postgresDatabase.name },
 ],
 },
 },
 },
});

The same is true for the client service, which is reduced to a short and easy to understand format. By default, React uses port 3000, but it can set to a different port. The SERVER_HOSTNAME environment variable is passed in when the container starts to generate a tiny configuration file at runtime called serverParams.js with the URL. This way, we do not have to rebuild the entire docker image should the server URL change.

const clientsideListener = new awsx.elasticloadbalancingv2.NetworkListener("client-side-listener", { port: 3000 });
const clientsideService = new awsx.ecs.FargateService("client-side-service", {
 taskDefinitionArgs: {
 containers: {
 clientsideService: {
 image: awsx.ecs.Image.fromPath("client-side-service", "./clientside"),
 memory: 512,
 portMappings: [clientsideListener],
 environment: [
 { name: "SERVER_HOSTNAME", value: serversideListener.endpoint.hostname },
 ],
 },
 },
 },
});

To make our PERN stack application available on the Internet, we export the clientside listener’s address. We can open a browser window with the URL and port to view our application.

export const URL = clientsideListener.endpoint.hostname;

In this example, I explained the basic principles behind PERN stack applications and showed how to create the infrastructure to deploy them on ECS. A flexible and optimized tool, Pulumi Crosswalk supports rapidly prototyping applications, scaling workloads, securing and integrating applications in existing infrastructure, and going to production in multiple complex environments.

Next week, I’ll demonstrate how to integrate applications with Kubernetes, and seamlessly deploy them to EKS using Pulumi.

The blog post’s code can be found on Github.

How to Deploy a Django Application to AWS

Vova Ivanov — Fri, 28 Aug 2020 00:00:00 +0000

In this blog post, we will finish swapping out the frontend and backend of our Python AWS application. Although Flask and Redis are different from Django and MySQL in many ways, the underlying infrastructure behind their deployment is nonetheless very similar, and can be effortlessly updated as we transition from one to the other.

We will be paying additional attention to security, and will be making use of Pulumi’s secret management tools to protect our passwords and private keys.

The first step is to create a new directory and initialize a Pulumi project with pulumi new aws-python.

$ mkdir aws-py-django-voting-app && cd aws-py-django-voting-app
$ pulumi new aws-python

Next, let’s create a folder to hold our application and start a Django project in it.

$ mkdir frontend && cd frontend
$ django-admin startproject mysite
$ cd mysite

This tutorial was written for the aws-py-django-voting-app example but will work with any other Django application. The most important file is ./mysite/settings.py, which we will modify to accept secrets and configuration parameters in the form of environment variables. A common mistake that programmers make is to submit files with important data to source code repositories. Even if it is a private repository, it is still not recommended to leave passwords and private keys in your files.

SECRET_KEY = os.environ['SECRET_KEY']

DATABASES = {
 'default': {
 'ENGINE': 'django.db.backends.mysql',
 'NAME': os.environ['DATABASE_NAME'],
 'USER': os.environ['USER_NAME'],
 'PASSWORD': os.environ['USER_PASSWORD'],
 'HOST': os.environ['DATABASE_ADDRESS'],
 'PORT': os.environ['DATABASE_PORT'],
 }
}

To perform database migrations as part of the deployment, we will create a setupDatabase.sh script inside the aws-py-django-voting-app/frontend/mysite folder. As a bonus, the script will create an admin account that we can use to log into our website. Make sure the file has exec permissions.

#!/bin/bash
set -exu
python3 /mysite/manage.py makemigrations
python3 /mysite/manage.py migrate
export DJANGO_SUPERUSER_PASSWORD=$DJANGO_PASSWORD
python3 /mysite/manage.py createsuperuser \
 --no-input \
 --username=$DJANGO_NAME \
 --email=$DJANGO_NAME@example.com

The next step is to go back into the aws-py-django-voting-app/frontend folder and containerize our application with Docker. First, we will list the libraries our application uses by creating a requirements.txt file with the following lines.

django==3.1
mysqlclient==1.4.0

And lastly, we can create the Dockerfile.

FROM ubuntu:18.04

WORKDIR /

EXPOSE 80

RUN apt-get update && \
 apt install -y gcc python3-dev python3-pip mysql-client-core-5.7 libmysqlclient-dev

ADD requirements.txt /

RUN pip3 install -r requirements.txt

ADD mysite /mysite

CMD [ "python3", "/mysite/manage.py", "runserver", "0.0.0.0:80" ]

Now that our Django application and Dockerfile are ready, we can return to the main aws-py-django-voting-app folder. The Pulumi project requires several configuration variables, which we set using pulumi config set. They are used to configure the MySQL admin account, a user account for initializing the table, and the Django website admin account. The private key that Django uses will also be passed in the same way.

$ pulumi config set sql-admin-name <NAME>
$ pulumi config set sql-admin-password <PASSWORD> --secret
$ pulumi config set sql-user-name <NAME>
$ pulumi config set sql-user-password <PASSWORD> --secret
$ pulumi config set django-admin-name <NAME>
$ pulumi config set django-admin-password <PASSWORD> --secret
$ pulumi config set django_secret_key = <VALUE> --secret

The requirements.txt file lists the libraries used by the project. We will need to add the following:

pulumi-docker>=2.0.0,<3.0.0
pulumi-mysql>=2.0.0,<3.0.0
mysql-connector-python>=1.0.0,<10.0.0

The first few lines of our __main__.py file indicate the libraries to import and describe the application’s configuration options.

import json
import base64
import pulumi
import pulumi_aws as aws
import pulumi_docker as docker
import pulumi_mysql as mysql

config = pulumi.Config()
sql_admin_name = config.require("sql-admin-name")
sql_admin_password = config.require_secret("sql-admin-password")
sql_user_name = config.require("sql-user-name")
sql_user_password = config.require_secret("sql-user-password")
availability_zone = pulumi.Config("aws").get("region")

django_admin_name = config.require("django-admin-name")
django_admin_password = config.require_secret("django-admin-password")

django_secret_key = config.require_secret("django-secret-key")

After setting up the imports and configurations, we create an ECS Cluster, VPC, Subnet, RDS instance, and several other items. All the components are identical to the ones in the first and second blog posts, and the full code can be seen in this example’s github repository.

app_cluster = aws.ecs.Cluster(...)

app_vpc = aws.ec2.Vpc(...)
app_vpc_subnet = aws.ec2.Subnet(...)

app_gateway = aws.ec2.InternetGateway(...)
app_routetable = aws.ec2.RouteTable(...)
app_security_group = aws.ec2.SecurityGroup(...)

app_exec_role = aws.iam.Role(...)
exec_policy_attachment = aws.iam.RolePolicyAttachment(...)
app_task_role = aws.iam.Role(...)
task_policy_attachment = aws.iam.RolePolicyAttachment(...)
task_policy_attachment = aws.iam.RolePolicyAttachment(...)

app_ecr_repo = aws.ecr.Repository(...)
app_lifecycle_policy = aws.ecr.LifecyclePolicy(...)

extra_rds_subnet = aws.ec2.Subnet(...)
app_database_subnetgroup = aws.rds.SubnetGroup(...)
mysql_rds_server = aws.rds.Instance(...)
mysql_provider = mysql.Provider(...)
mysql_database = mysql.Database(...)
mysql_user = mysql.User(...)
mysql_access_grant = mysql.Grant(...)

With the basic infrastructure and MySQL backend in place, all that’s left is to create the Django frontend.

A target group, balancer, and listener are created for the frontend.

django_targetgroup = aws.lb.TargetGroup("django-targetgroup",
 port=80,
 protocol="TCP",
 target_type="ip",
 stickiness= {
 "enabled": False,
 "type": "lb_cookie",
 },
 vpc_id=app_vpc.id)

django_balancer = aws.lb.LoadBalancer("django-balancer",
 load_balancer_type="network",
 internal=False,
 security_groups=[],
 subnets=[app_vpc_subnet.id])

django_listener = aws.lb.Listener("django-listener",
 load_balancer_arn=django_balancer.arn,
 port=80,
 protocol="TCP",
 default_actions=[{
 "type": "forward",
 "target_group_arn": django_targetgroup.arn
 }])

The application is built into a Docker image and pushed to our ECR repository we created earlier.

def get_registry_info(rid):
 creds = aws.ecr.get_credentials(registry_id=rid)
 decoded = base64.b64decode(creds.authorization_token).decode()
 parts = decoded.split(':')
 if len(parts) != 2:
 raise Exception("Invalid credentials")
 return docker.ImageRegistry(creds.proxy_endpoint, parts[0], parts[1])

app_registry = app_ecr_repo.registry_id.apply(get_registry_info)

django_image = docker.Image("django-dockerimage",
 image_name=app_ecr_repo.repository_url,
 build="./frontend",
 skip_push=False,
 registry=app_registry
)

To help with debugging our application, we will create a Cloudwatch instance to store all logs.

django_log_group = aws.cloudwatch.LogGroup("django-log-group",
 retention_in_days=1,
 name="django-log-group"
)

Our project is special because it uses two independent ECS services—one that sets up the MySQL database, and one that continuously runs and handles the website.

While it is possible to have a single ECS service set up both the database and the server, doing so presents the risk of exposing important information to the internet. To set up the database, the ECS service would need to know our MySQL admin credentials. However, since the service would also handle the website, it would mean that a successful attack on our Django website could allow the attacker to access the credentials for our backend.

First, let’s create the task definition that runs once and sets up the database.

django_database_task_definition = aws.ecs.TaskDefinition("django-database-task-definition",
 family="django_database_task_definition-family",
 cpu="256",
 memory="512",
 network_mode="awsvpc",
 requires_compatibilities=["FARGATE"],
 execution_role_arn=app_exec_role.arn,
 task_role_arn=app_task_role.arn,
 container_definitions=pulumi.Output.all(
 # We must do Output.all() to access Pulumi secrets
 django_image.image_name,
 django_secret_key,
 mysql_database.name,
 sql_admin_name,
 sql_admin_password,
 django_admin_name,
 django_admin_password,
 mysql_rds_server.address,
 mysql_rds_server.port).apply(lambda args: json.dumps([{
 "name": "django-container",
 "image": args[0],
 "memory": 512,
 "essential": True,
 "portMappings": [{
 "containerPort": 80,
 "hostPort": 80,
 "protocol": "tcp"
 }],
 "environment": [
 { "name": "SECRET_KEY", "value": args[1] },
 { "name": "DATABASE_NAME", "value": args[2] },
 { "name": "USER_NAME", "value": args[3] },
 { "name": "USER_PASSWORD", "value": args[4] },
 { "name": "DJANGO_NAME", "value": args[5] },
 { "name": "DJANGO_PASSWORD", "value": args[6] },
 { "name": "DATABASE_ADDRESS", "value": args[7] },
 { "name": "DATABASE_PORT", "value": str(int(args[8])) },
 ],
 "logConfiguration": {
 "logDriver": "awslogs",
 "options": {
 "awslogs-group": "django-log-group",
 "awslogs-region": "us-west-2",
 "awslogs-stream-prefix": "djangoApp-database",
 },
 },
 # We override the command in the Dockerfile with a new one
 "command": ["/mysite/setupDatabase.sh"]
 }])))

We can now launch our first service on Fargate.

django_database_service = aws.ecs.Service("django-database-service",
 cluster=app_cluster.arn,
 desired_count=1,
 launch_type="FARGATE",
 task_definition=django_database_task_definition.arn,
 wait_for_steady_state=False,
 network_configuration={
 "assign_public_ip": "true",
 "subnets": [app_vpc_subnet.id],
 "security_groups": [app_security_group.id]
 },
 load_balancers=[{
 "target_group_arn": django_targetgroup.arn,
 "container_name": "django-container",
 "container_port": 80,
 }],
 opts=pulumi.ResourceOptions(depends_on=[django_listener]),
)

Finally, let’s create the second task definition to run the website.

django_site_task_definition = aws.ecs.TaskDefinition("django-site-task-definition",
 family="django-site-task-definition-family",
 cpu="256",
 memory="512",
 network_mode="awsvpc",
 requires_compatibilities=["FARGATE"],
 execution_role_arn=app_exec_role.arn,
 task_role_arn=app_task_role.arn,
 container_definitions=pulumi.Output.all(
 django_image.image_name,
 django_secret_key,
 mysql_database.name,
 sql_user_name,
 sql_user_password,
 mysql_rds_server.address,
 mysql_rds_server.port).apply(lambda args: json.dumps([{
 "name": "django-container",
 "image": args[0],
 "memory": 512,
 "essential": True,
 "portMappings": [{
 "containerPort": 80,
 "hostPort": 80,
 "protocol": "tcp"
 }],
 "environment": [
 { "name": "SECRET_KEY", "value": args[1] },
 { "name": "DATABASE_NAME", "value": args[2] },
 { "name": "USER_NAME", "value": args[3] },
 { "name": "USER_PASSWORD", "value": args[4] },
 { "name": "DATABASE_ADDRESS", "value": args[5] },
 { "name": "DATABASE_PORT", "value": str(int(args[6])) },
 ],
 "logConfiguration": {
 "logDriver": "awslogs",
 "options": {
 "awslogs-group": "django-log-group",
 "awslogs-region": "us-west-2",
 "awslogs-stream-prefix": "djangoApp-site",
 },
 },
 }])))

Similarly, we will launch our second task definition on Fargate.

django_site_service = aws.ecs.Service("django-site-service",
 cluster=app_cluster.arn,
 desired_count=1,
 launch_type="FARGATE",
 task_definition=django_site_task_definition.arn,
 wait_for_steady_state=False,
 network_configuration={
 "assign_public_ip": "true",
 "subnets": [app_vpc_subnet.id],
 "security_groups": [app_security_group.id]
 },
 load_balancers=[{
 "target_group_arn": django_targetgroup.arn,
 "container_name": "django-container",
 "container_port": 80,
 }],
 opts=pulumi.ResourceOptions(depends_on=[django_listener]),

To connect to our application, we export the DNS name of the Django balancer and open it in a browser window.

pulumi.export("app-url", django_balancer.dns_name)

To add questions to the database, add “/admin/” to the end of the URL, and log in using your Django admin credentials.

The Administration panel allows you to manage the state of your application. Groups, users, choices, and questions can all be added easily.

Comparison between Flask and Django:

In this example, I described how to set up a basic Django voting application and deploy it to AWS. Although our Django and Flask applications use very different AWS services, we seamlessly replaced the previous infrastructure with what was needed.

Next week, we’ll explore PostgreSQL, Express, React, and Node.js, and use them to create a simple application.

The blog post’s full code and an in-depth explanation for each component are on Github.

Creating a Python AWS Application Using Flask and Redis

Vova Ivanov — Thu, 13 Aug 2020 15:06:26 -0700

Meet Vova Ivanov—one of the Pulumi summer interns. He’ll be writing about his experiences learning Pulumi while modernizing a web app and its underlying infrastructure.

I’ve recently started developing with Pulumi, and have begun to explore its inner workings and mechanisms. I decided to construct a production-level application and to document each step that I take and my progress as I go along.

This blog post recreates the existing Typescript voting app example step by step in Python with Flask as the frontend and Redis as the backend. In future blog posts, we will explore how to change the front and backends, how to upgrade the app with additional AWS services, and migrating from one cloud provider to another.

The first step is to clone the Typescript voting app example. We’ll use a sparse clone to copy only the aws-ts-voting-app directory.

$ mkdir examples && cd examples
$ git init
$ git remote add origin -f https://github.com/pulumi/examples/
$ git config core.sparseCheckout true
$ echo aws-ts-voting-app >> .git/info/sparse-checkout
$ git pull origin master

The next step is to create a new directory and initialize a Pulumi project with pulumi new aws-python.

$ mkdir aws-py-voting-app && cd aws-py-voting-app
$ pulumi new aws-python

Since we won’t be modifying the application’s frontend, we simply copy the frontend/ folder from the example into our directory.

$ cp -r aws-ts-voting-app/frontend/ aws-py-voting-app/frontend

The requirements.txt file lists the libraries that the project depends on. We will need to add the following:

pulumi-docker>=2.0.0,<3.0.0

The biggest difference between our project and the example is the code describing the cloud infrastructure we want to create. Instead of an index.ts file, the project uses a __main__.py file. The first few lines of the file will indicate which libraries to import and describe a pair of configuration options used by the application.

import json
import pulumi
import pulumi_aws as aws
import pulumi_docker as docker

config = pulumi.Config()
redis_password = config.require("redis-password")
redis_port = 6379

After setting up the imports and configurations, we create an Elastic Container Service Cluster. A Cluster represents a group of tasks and services that work together for a certain purpose. In this instance, the purpose is to provide users with a voting application.

app_cluster = aws.ecs.Cluster("app-cluster")

To allow different tasks within our cluster to communicate, we create a Virtual Private Cloud and an associated subnet.

app_vpc = aws.ec2.Vpc("app-vpc",
 cidr_block="172.31.0.0/16",
 enable_dns_hostnames=True)

app_vpc_subnet = aws.ec2.Subnet("app-vpc-subnet",
 cidr_block="172.31.32.0/20",
 vpc_id=app_vpc)

A gateway and routing table are needed to allow the VPC to communicate with the Internet. Once created, we associate the routing table with our VPC.

app_gateway = aws.ec2.InternetGateway("app-gateway",
 vpc_id=app_vpc.id)

app_routetable = aws.ec2.RouteTable("app-routetable",
 routes=[
 {
 "cidr_block": "0.0.0.0/0",
 "gateway_id": app_gateway.id,
 }
 ],
 vpc_id=app_vpc.id)

app_routetable_association = aws.ec2.MainRouteTableAssociation("app_routetable_association",
 route_table_id=app_routetable.id,
 vpc_id=app_vpc)

To control traffic flow between applications running inside our VPC, we create a security group.

app_security_group = aws.ec2.SecurityGroup("security-group",
 vpc_id=app_vpc.id,
 description="Enables HTTP access",
 ingress=[{
 'protocol': 'tcp',
 'from_port': 0,
 'to_port': 65535,
 'cidr_blocks': ['0.0.0.0/0'],
 }],
 egress=[{
 'protocol': '-1',
 'from_port': 0,
 'to_port': 0,
 'cidr_blocks': ['0.0.0.0/0'],
 }])

To start our services, we need to create an Identity and Access Management (IAM) role, and attach execution permissions to it.

app_exec_role = aws.iam.Role("app-exec-role",
 assume_role_policy="""{
 "Version": "2012-10-17",
 "Statement": [
 {
 "Action": "sts:AssumeRole",
 "Principal": {
 "Service": "ecs-tasks.amazonaws.com"
 },
 "Effect": "Allow",
 "Sid": ""
 }]
 }""")

exec_policy_attachment = aws.iam.RolePolicyAttachment("app-exec-policy", role=app_exec_role.name,
 policy_arn=aws.iam.ManagedPolicy.AMAZON_ECS_TASK_EXECUTION_ROLE_POLICY)

Likewise, our ECS service will need to have a task role to manage it, along with its own set of permissions.

app_task_role = aws.iam.Role("app-task-role",
 assume_role_policy="""{
 "Version": "2012-10-17",
 "Statement": [
 {
 "Action": "sts:AssumeRole",
 "Principal": {
 "Service": "ecs-tasks.amazonaws.com"
 },
 "Effect": "Allow",
 "Sid": ""
 }]
 }""")

task_policy_attachment = aws.iam.RolePolicyAttachment("app-access-policy", role=app_task_role.name,
 policy_arn=aws.iam.ManagedPolicy.AMAZON_ECS_FULL_ACCESS)

An Elastic Container Registry Repository stores the application Docker images that we want to run. The life cycle policy automatically removes the oldest untagged image that we uploaded.

app_ecr_repo = aws.ecr.Repository("app-ecr-repo",
 image_tag_mutability="MUTABLE")

app_lifecycle_policy = aws.ecr.LifecyclePolicy("app-lifecycle-policy",
 repository=app_ecr_repo.name,
 policy="""{
 "rules": [
 {
 "rulePriority": 10,
 "description": "Remove untagged images",
 "selection": {
 "tagStatus": "untagged",
 "countType": "imageCountMoreThan",
 "countNumber": 1
 },
 "action": {
 "type": "expire"
 }
 }
 ]
 }""")

With the basic infrastructure in place, we can begin to set up the application itself. First, we will start with the Redis backend.

We need to create a target group, a balancer, and a listener to allow Redis to communicate with the other services in our VPC, w

redis_targetgroup = aws.lb.TargetGroup("redis-targetgroup",
 port=redis_port,
 protocol="TCP",
 target_type="ip",
 stickiness= {
 "enabled": False,
 "type": "lb_cookie",
 },
 vpc_id=app_vpc.id)

redis_balancer = aws.lb.LoadBalancer("redis-balancer",
 load_balancer_type="network",
 internal= False,
 security_groups=[],
 subnets=[app_vpc_subnet.id])

redis_listener = aws.lb.Listener("redis-listener",
 load_balancer_arn=redis_balancer.arn,
 port=redis_port,
 protocol="TCP",
 default_actions=[{
 "type": "forward",
 "target_group_arn": redis_targetgroup.arn
 }])

Every service running within ECS requires a task definition, specifying what hardware, internet, and container settings it will use.

redis_task_definition = aws.ecs.TaskDefinition("redis-task-definition",
 family="redis-task-definition-family",
 cpu="256",
 memory="512",
 network_mode="awsvpc",
 requires_compatibilities=["FARGATE"],
 execution_role_arn=app_exec_role.arn,
 task_role_arn=app_task_role.arn,
 container_definitions=json.dumps([{
 "name": "redis-container",
 "image": "redis:alpine",
 "memory": 512,
 "essential": True,
 "portMappings": [{
 "containerPort": redis_port,
 "hostPort": redis_port,
 "protocol": "tcp"
 }],
 "command": ["redis-server", "--requirepass", redis_password],
 }]))

Now that we have our task definition blueprint ready, we can launch a service using it. An endpoint is created to hold information needed to connect the backend with the frontend.

redis_service = aws.ecs.Service("redis-service",
 cluster=app_cluster.arn,
 desired_count=1,
 launch_type="FARGATE",
 task_definition=redis_task_definition.arn,
 wait_for_steady_state=False,
 network_configuration={
 "assign_public_ip": "true",
 "subnets": [app_vpc_subnet.id],
 "security_groups": [app_security_group.id]
 },
 load_balancers=[{
 "target_group_arn": redis_targetgroup.arn,
 "container_name": "redis-container",
 "container_port": redis_port,
 }],
 opts=pulumi.ResourceOptions(depends_on=[redis_listener]),
)

redis_endpoint = {"host": redis_balancer.dns_name, "port": redis_port}

The Redis backend is complete, and now all that’s left is to create the Flask frontend.

A similar set of a target group, balancer, and listener is created for the frontend. Unlike Redis, Flask will serve as the webpage and, as such, needs to receive its data from port 80.

flask_targetgroup = aws.lb.TargetGroup("flask-targetgroup",
 port=80,
 protocol="TCP",
 target_type="ip",
 stickiness= {
 "enabled": False,
 "type": "lb_cookie",
 },
 vpc_id=app_vpc.id)

flask_balancer = aws.lb.LoadBalancer("flask-balancer",
 load_balancer_type="network",
 internal=False,
 security_groups=[],
 subnets=[app_vpc_subnet.id])

flask_listener = aws.lb.Listener("flask-listener",
 load_balancer_arn=flask_balancer.arn,
 port=80,
 protocol="TCP",
 default_actions=[{
 "type": "forward",
 "target_group_arn": flask_targetgroup.arn
 }])

The application is built into a Docker image and pushed to our ECR repository we created earlier.

def get_registry_info(rid):
 creds = aws.ecr.get_credentials(registry_id=rid)
 decoded = base64.b64decode(creds.authorization_token).decode()
 parts = decoded.split(':')
 if len(parts) != 2:
 raise Exception("Invalid credentials")
 return docker.ImageRegistry(creds.proxy_endpoint, parts[0], parts[1])

app_registry = app_ecr_repo.registry_id.apply(get_registry_info)

flask_image = docker.Image("flask-dockerimage",
 image_name=app_ecr_repo.repository_url,
 build="./frontend",
 skip_push=False,
 registry=app_registry
)

A task definition is created for the frontend; this time, using the flask image that we built. The redis endpoint is passed in as a group of environment variables, informing our app of our database’s host and port values.

flask_task_definition = aws.ecs.TaskDefinition("flask-task-definition",
 family="frontend-task-definition-family",
 cpu="256",
 memory="512",
 network_mode="awsvpc",
 requires_compatibilities=["FARGATE"],
 execution_role_arn=app_exec_role.arn,
 task_role_arn=app_task_role.arn,
 container_definitions=pulumi.Output.all(flask_image.image_name, redis_endpoint).apply(lambda args: json.dumps([{
 "name": "flask-container",
 "image": args[0],
 "memory": 512,
 "essential": True,
 "portMappings": [{
 "containerPort": 80,
 "hostPort": 80,
 "protocol": "tcp"
 }],
 "environment": [
 { "name": "REDIS", "value": args[1]["host"] },
 { "name": "REDIS_PORT", "value": str(args[1]["port"]) },
 { "name": "REDIS_PWD", "value": redis_password },
 ],
 }])))

The service for our Flask frontend is launched. It can receive requests from the Internet, process them, and change the Redis database accordingly.

flask_service = aws.ecs.Service("flask-service",
 cluster=app_cluster.arn,
 desired_count=1,
 launch_type="FARGATE",
 task_definition=flask_task_definition.arn,
 wait_for_steady_state=False,
 network_configuration={
 "assign_public_ip": "true",
 "subnets": [app_vpc_subnet.id],
 "security_groups": [app_security_group.id]
 },
 load_balancers=[{
 "target_group_arn": flask_targetgroup.arn,
 "container_name": "flask-container",
 "container_port": 80,
 }],
 opts=pulumi.ResourceOptions(depends_on=[flask_listener]),
)

To connect to our application, we export the DNS name of the Flask balancer, and open it in a browser window.

pulumi.export("app-url", flask_balancer.dns_name)

In this example, I showed how straightforward it is to convert infrastructure code defined in TypeScript to one defined in Python. Teams often choose to standardize on one language and Pulumi expands that choice, allowing them to standardize on one language for the frontend, the backend, and the infrastructure.

Next week, I’ll show how to modernize the application by changing the frontend from Flask to Django, and swapping out the database from Redis to Amazon RDS—using Pulumi to stand up new resources as I go.

The full code for the blog post can be found on github.

Build a Pulumi VS Code Devcontainer Environment

Sophia Parafina — Tue, 14 Jul 2020 00:00:00 +0000

One of the major advantages of using containers for development is reducing the need to install software and associated dependencies. Developers can start writing code without configuring a development environment that emulates production. The Visual Studio Code Remote - Containers extension lets you develop inside a container. If you want to use Pulumi’s infrastructure as code engine without installing the Pulumi CLI, this blog post is for you!

Pre-requisites

To set up your development environment, you’ll need Visual Studio Code, Docker Desktop, and the Remote - Containers extension.

Check to see if Docker is running:

$ docker --version
Docker version 19.03.8, build afacb8b

Check to see if the Remote - Containers is installed:

Click on the green icon in the Remote Status Bar to display the commands:

Building the Pulumi container

Now we can start!

Create a directory for your project.
```
$ mkdir my_devcontainer
$ cd my_devcontainer
```
Open the directory in VS Code.
Next, we’ll create the devcontainer configuration files. Click on the Remote Status button and select Add Development Container Configuration Files ….
Select the latest version for Alpine. We’ll replace the Dockerfile with the Pulumi Dockerfile.

VS Code will display a popup asking to build the container. Dismiss the popup, we will replace the Dockerfile with the Pulumi Dockerfile.

In your project directory, you’ll see a .devcontainer directory with a Dockerfile that builds the container and a devcontainer.json for configuring the container environment.

Dockerfile

For this example, we’ll use the standard Pulumi Dockerfile, which includes the SDK for all the supported languages. Download the Dockerfile and save it to the .devcontainer directory.

$ cd .devcontainer
$ curl "https://raw.githubusercontent.com/pulumi/pulumi/master/.devcontainer/Dockerfile" -o Dockerfile

Container configuration

Next, we’ll clean up the .devcontainer/devcontainer.json file and set up the necessary credentials.

First edit devcontainer.json as follows:

Replace the “name” field with Pulumi
Remove the “args” line
Replace the “remoteUser” value with user

Regardless of your cloud provider, you will have to provide your credentials to deploy resources. If you want to save your project to Github or another repository, you don’t want your credentials stored in the repository. There are several ways to do this securely. Using AWS as an example, you can export them inside the container, e.g.,

Linux/macOS:

export AWS_ACCESS_KEY_ID=AKIAI44QH8DHBEXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Windows:

SET AWS_ACCESS_KEY_ID=AKIAI44QH8DHBEXAMPLE
SET AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

The disadvantage of this method is that you will have to set these environment variables every time you start the devcontainer.

Use local environment variables

One alternative is to set the environment variables on your local machine and pass them to the container through the devcontainer.json file. This method requires that you have VS Code in your path and launch it from the shell.

Use CTRL+SHIFT+P or CMD+SHIFT+P to bring up the command palette and type Shell Command: Install ‘code’ command in PATH. You can set your credentials as environmental variables and launch the VS Code from the shell
```
$ export AWS_ACCESS_KEY_ID=AKIAI44QH8DHBEXAMPLE
$ export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
$ code .
```

Next, set your provider credentials on your machine and add the following to devcontainer.json.

"containerEnv": {
 "AWS_ACCESS_KEY_ID": "${localEnv:AWS_ACCESS_KEY_ID}",
 "AWS_SECRET_ACCESS_KEY": "${localEnv:AWS_SECRET_ACCESS_KEY}"
},

Use an .env file

Another alternative is to use a devcontainer.env file, which contains your credentials.

Create a file with your credentials.

AWS_ACCESS_KEY_ID=AKIAI44QH8DHBEXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Then add it to the devcontainer.json file.

"runArgs": ["--env-file","devcontainer.env"],

To prevent it from exposing your credentials on a public repository, add the file to .gitignore or similar for you repository, e.g.,
```
echo devcontainer.json > .gitignore
```

There are many more configuration options available, including mounts and remote configurations.

Try it out

Again, use the command palette to start the container. Use the Open Folder in Container… command, and select the project folder. If you’ve already got the folder open locally, you could also use the Reopen in Container command.

Check to see if your credentials are set. Open a terminal in VS Code if it isn’t already open.

$ user@973a612c1555:/workspaces/my_devcontainer# env | grep AWS
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_ACCESS_KEY_ID=AKIAI44QH8DHBEXAMPLE

Now we ready to use Pulumi in our VS Code development environment! Let’s try it out by creating an S3 bucket. First, we’ll make a directory for our project and use pulumi new to create a default project.

$ mkdir my_project
$ cd my_project
$ pulumi new aws-typescript

Follow the prompts, then run pulumi up to deploy.

$ pulumi up
Previewing update (dev):
 Type Name Plan
 + pulumi:pulumi:Stack my_project-dev create
 + └─ aws:s3:Bucket my-bucket create

Resources:
 + 2 to create

Do you want to perform this update? yes
Updating (dev):
 Type Name Status
 + pulumi:pulumi:Stack my_project-dev created
 + └─ aws:s3:Bucket my-bucket created

Outputs:
 bucketName: "my-bucket-cbdec06"

Resources:
 + 2 created

Duration: 31s

Permalink: https://app.pulumi.com/spara/my_project/dev/updates/1

You can CMD + click on the link to open a browser and display the status of your project on the Pulumi Service.

Build a Pulumi examples devcontainer

Pulumi has a repository of examples, and we can create a devcontainer from the repository so you can try them out.

Clone the repository, then follow the steps above to create and configure the Pulumi container image.
```
$ git clone https://github.com/pulumi/examples.git
```
Create the configuration files, add the Pulumi Docker file, and add your credentials.
Let’s deploy a Kubernetes cluster! With pulumi stack init, we can create a stack, but we will need to install the project dependencies and set configuration variables such as the region.
```
$ cd aws-ts-eks
$ pulumi stack init
$ npm install
$ pulumi config set aws:region us-west-2
$ pulumi up
```

Here’s the kubeconfig file’s output, which you can use with kubectl to manage the cluster.

Outputs:
 kubeconfig: {
 apiVersion : "v1"
 clusters : [
 [0]: {
 cluster: {
 certificate-authority-data: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUN5RENDQWJDZ0F3SUJBZ0lCQURBTkJna3Foa2lHOXcwQkFRc0ZBREFWTVJNd0VRWURWUVFERXdwcmRXSmwKY201bGRHVnpNQjRYRFRJd01EY3hNVEl5TXpZMU9Wb1hEVE13TURjd09USXlNelkxT1Zvd0ZURVRNQkVHQTFVRQpBeE1LYTNWaVpYSnVaWFJsY3pDQ0FTSXdEUVlKS29aSWh2Y05BUUVCQlFBRGdnRVBBRENDQVFvQ2dnRUJBTHFvCk9wTDBiQWo2TFFMNlh2anRsMFZ6TUN5WTJmYlo4cXEvNGd3bkJxcVI2RFV6Q1RwbkJmOHJVRjVrUXhBQXRUNysKTTFZblp5VEFBYndOZ3NIL3lObk5sMnFCQmRSQ0JZTVVlN1I2MVBxcGdabFZpN0JaNHRlek9DalRqeGV0SXlaMwoxRW9TdTNBYnhzTmh6dDVBTjVYZklnZlBuM3B2eEtwYTA1MEg3aWhFaUptSEl3M0Z5TVovUHpxY2JHczh3RHVCCk1jYjNzOHMwZDBIVExsb2dCL2svOVBLbGVpZDgyWFkxMEdBN0YxeFM2cFdZODkwQ1BwNXpWZ0pRWGhuRGR2S1gKVlFValdCTDZQYU14U0lBZEZQM1BZYk1FdXk5Vyt0c2lqc2VydThVNTVpUDlWSUdMdTZzdEdycTNuQUhtUk40UQpqeXRCRWd4RjN1R0dtZ0dMOStFQ0F3RUFBYU1qTUNFd0RnWURWUjBQQVFIL0JBUURBZ0trTUE4R0ExVWRFd0VCCi93UUZNQU1CQWY4d0RRWUpLb1pJaHZjTkFRRUxCUUFEZ2dFQkFEcUtyVGVnZmhWbElNUklQNjFVZEtvaGtnS3MKblUyZjUvTHBzU3ozbmliUCt3Y2VpNktYL3RSNjAzTHhFMlVXUTlmR0ZycTBCMTlJR1JaK0VVQjl2Vy9JdWowTApVK2UwUUtWc01qd2dMWm4rS3IyN0VQNUNGay8vZEVCRUZqa01PMmNlTFFRaFcvUXFzSFhJb2ZjZ0UvZnJ3YzErCmQwdGROWmxJa3JRdzJwYnVhcVI0VmRlWlpVSitqbW8rdEo1SlZ5a2Rwa29JYml1ZEZ6Q0N5YVB1LzhJc09CTUsKcWtvTFpNazdBMzh5SWxDK2RCTnJwdkQvRTF5U1lhcXlDaE5CdVBkd1VqcWZaWmJmaWR5N050emd2VjMvUWFtWgpuZUJJcWs0c1AzSWU0TUN0QmV4bU9iSWowdVBLTnVCQ01UTStxSVI2UWdnYXdEbWxXcXE4V0ZiUlNJMD0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo="
 server : "https://3FE47B904E57AF9E16E0B7F00C7EEABA.yl4.us-west-2.eks.amazonaws.com"
 }
 name : "kubernetes"
 }
 ]
 contexts : [
 [0]: {
 context: {
 cluster: "kubernetes"
 user : "aws"
 }
 name : "aws"
 }
 ]
 current-context: "aws"
 kind : "Config"
 users : [
 [0]: {
 name: "aws"
 user: {
 exec: {
 apiVersion: "client.authentication.k8s.io/v1alpha1"
 args : [
 [0]: "eks"
 [1]: "get-token"
 [2]: "--cluster-name"
 [3]: "cluster-eksCluster-367b66b"
 ]
 command : "aws"
 }
 }
 }
 ]
 }

You can now try out any of our infrastructure as code examples with this devcontainer.

Conclusion

As you can see, we’ve built our development with VS Code and Docker. Using a Pulumi devcontainer lets you build and deploy infrastructure without installing Pulumi or any associated dependencies on your computer. Moreover, you can share your development environment by creating a repository. Give it a try and let us know what you’re building on Slack or Twitter.

Introducing New Slimmer Docker Images

Lee Briggs — Thu, 25 Jun 2020 00:00:00 +0000

One of the most exciting aspects of using Pulumi can also present some interesting engineering challenges. Pulumi supports three operating systems, multiple programming languages, and almost 40 different providers. This means creating tooling that works effortlessly across all possible user scenarios can often throw unexpected challenges our way.

Nowhere are these challenges more prevalent than in the Pulumi Docker containers.

The pulumi/pulumi Docker container is almost 3Gb uncompressed, which is generally considered large for a Docker image. In this post, I’ll examine why this container has grown to the size that it is, and talk about how we hope to solve it.

Anatomy of a Pulumi Program

Pulumi has the unique ability to interact with cloud providers across many boundaries. As an example, you might want to provision a Kubernetes cluster and install a Helm chart onto that cluster. Pulumi lets you do that from a single “Pulumi program”, here’s an example:

import * as digitalocean from "@pulumi/digitalocean";
import * as k8s from "@pulumi/kubernetes";
import * as pulumi from "@pulumi/pulumi";

const config = new pulumi.Config();
const nodeCount = config.getNumber("nodeCount") || 1;

// Create a Kubernetes Cluster in DigitalOcean
const cluster = new digitalocean.KubernetesCluster("do-cluster", {
 region: digitalocean.Regions.SFO2,
 version: digitalocean.getKubernetesVersions({versionPrefix: "1.16"}).then(p => p.latestVersion),
 nodePool: {
 name: "default",
 size: "s-1vcpu-2gb",
 nodeCount: nodeCount,
 },
});

// configure a kubernetes provider
const provider = new k8s.Provider("k8s", { kubeconfig: cluster.kubeConfigs[0].rawConfig })

const namespace = new k8s.core.v1.Namespace("ns", {
 metadata: {
 name: "nginx-ingress",
 }
}, { provider: provider });

// deploy nginx-ingress with helm
const nginx = new k8s.helm.v2.Chart("nginx-ingress",
 {
 namespace: namespace.metadata.name,
 chart: "nginx-ingress",
 version: "1.33.5",
 fetchOpts: { repo: "https://charts.helm.sh/stable/" },
 values: {
 controller: {
 replicaCount: 1,
 service: {
 type: "LoadBalancer",
 },
 publishService: {
 enabled: true,
 },
 },
 }
 },
 { providers: { kubernetes: provider } },
)

"""A DigitalOcean Python Pulumi program"""

import pulumi
import pulumi_kubernetes as k8s
import pulumi_digitalocean as do
import pulumi_kubernetes.helm.v3 as helm
from pulumi_kubernetes.core.v1 import Namespace

config = pulumi.Config()
node_count = config.get_float("nodeCount") or 1


# Create a Kubernetes Cluster in DigitalOcean
cluster = do.KubernetesCluster(
 "do-cluster",
 region="sfo2",
 version="1.16",
 node_pool={
 "name": "default",
 "size": "s-1vcpu-2gb",
 "nodeCount": node_count
 }

)

# Use the Kubeconfig output to create a k8s provider
k8s_provider = k8s.Provider("k8s", kubeconfig=cluster.kube_configs[0]["rawConfig"])

# Create a namespace using the previously retrieved kubernetes provider
namespace = Namespace(
 "ns",
 metadata={
 "name": "nginx-ingress"
 }, opts=pulumi.ResourceOptions(provider=k8s_provider))

chart = helm.Chart(
 "nginx-ingress",
 helm.ChartOpts(namespace="nginx-ingress",
 chart="nginx-ingress",
 version="1.33.5",
 fetch_opts=k8s.helm.v3.FetchOpts(
 repo="https://charts.helm.sh/stable/"
 ),
 values={
 "controller": {
 "replicaCount": 1,
 "service": {
 "type": "LoadBalancer"
 },
 "publishService": {
 "enabled": True,
 }
 }
 }), pulumi.ResourceOptions(provider=k8s_provider)
)

package main

import (
 "fmt"
 "github.com/pulumi/pulumi-digitalocean/sdk/v2/go/digitalocean"
 "github.com/pulumi/pulumi-kubernetes/sdk/v2/go/kubernetes"
 corev1 "github.com/pulumi/pulumi-kubernetes/sdk/v2/go/kubernetes/core/v1"
 "github.com/pulumi/pulumi-kubernetes/sdk/v2/go/kubernetes/helm/v2"
 metav1 "github.com/pulumi/pulumi-kubernetes/sdk/v2/go/kubernetes/meta/v1"
 "github.com/pulumi/pulumi/sdk/v2/go/pulumi"
)

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {

 // Create a Kubernetes cluster in DigitalOcean
 cluster, err := digitalocean.NewKubernetesCluster(ctx, "do-cluster", &digitalocean.KubernetesClusterArgs{
 Region: pulumi.String("sfo2"),
 Version: pulumi.String("1.16"),
 NodePool: &digitalocean.KubernetesClusterNodePoolArgs{
 Name: pulumi.String("default"),
 Size: pulumi.String("s-1vcpu-2gb"),
 },
 })

 if err != nil {
 return fmt.Errorf("Error creating cluster: ", err)
 }

 // Instantiate a Kubernetes provider
 provider, err := kubernetes.NewProvider(ctx, "k8s", &kubernetes.ProviderArgs{
 Kubeconfig: cluster.KubeConfigs.Index(pulumi.Int(0)).RawConfig(),
 })

 if err != nil {
 return fmt.Errorf("Error instantating Kubernetes provider: ", err)
 }

 // Create a namespace
 ns, err := corev1.NewNamespace(ctx, "nginx-ingress", &corev1.NamespaceArgs{
 Metadata: &metav1.ObjectMetaArgs{
 Name: pulumi.String("nginx-ingress"),
 },
 }, pulumi.Provider(provider))

 if err != nil {
 return fmt.Errorf("Error creating Kubernetes namespace: ", err)
 }

 // Deploy nginx-ingress using the helm chart
 _, err = helm.NewChart(ctx, "nginx-ingress", helm.ChartArgs{
 Chart: pulumi.String("nginx-ingress"),
 Version: pulumi.String("1.33.5"),
 Namespace: ns.Metadata.Name().Elem(),
 FetchArgs: &helm.FetchArgs{
 Repo: pulumi.String("https://charts.helm.sh/stable/"),
 },
 Values: pulumi.Map{
 "controller": pulumi.Map{
 "replicaCount": pulumi.Int(1),
 "service": pulumi.Map{
 "type": pulumi.String("LoadBalancer"),
 },
 "publishService": pulumi.Map{
 "enabled": pulumi.Bool(true),
 },
 },
 },
 }, pulumi.Provider(provider))

 return nil
 })
}

To achieve this level of interoperability, however, we need to have some dependencies installed locally. These are:

the Pulumi binary
the Pulumi language runtime for our chosen language
the language binary (e.g., node, python, DotNet or Go)
the languages’ dependency management tool (e.g., npm, yarn, PipEnv, etc.)
the Helm CLI for rendering the Helm chart to a template that Pulumi can then install

This list of requirements is already getting lengthy, and we’re only provisioning one piece of infrastructure. Alongside this, if you’re using this container in your CI/CD pipeline, you might also need to acquire credentials during the pulumi up process. When you consider that Pulumi’s users could be using any of our featured programming languages as well as one or many of our supported cloud providers, you’ll begin to imagine how many dependencies are needed.

To provide a seamless experience for our users, our existing pulumi/pulumi Docker image contains every possible dependency a user might need when provisioning cloud infrastructure. We install everything from the Helm CLI to the Azure CLI to ensure you can use the container for any Pulumi program. Unfortunately, as we began to support more cloud providers and more languages, the size of the image has grown considerably.

We’ve received fantastic feedback from the community that while this Docker image meets their needs, providing smaller images is desirable. Not only do our users want to see images that are smaller in size, but they also want a less opinionated image that provides the flexibility and customization needed to suit the complex workflows people can create with Pulumi.

Introducing new Language Specific Images

Starting from Pulumi version 2.4.0, we’ll be publishing new, slimmer images in the DockerHub that contain fewer dependencies and are focused on individual specific languages. We’ve built these images to be usable from day 1, and many of our pioneering users have been using them successfully. Each image contains everything you need to use Pulumi for your programming language of choice, including the Pulumi CLI, the Pulumi language runtime, and the language binary and dependency manager).

Reduced Size

Removing many dependencies and only installing a single language SDK means we’ve seen a dramatic decrease in the uncompressed size of the images:

As you can see below, the uncompressed images are up to six times smaller than the pulumi/pulumi container, which means a much smaller surface area and considerably quicker pull times.

Image Name	Compressed Size	Uncompressed Size
pulumi/pulumi:v2.4.0	856.33 MB	2.97GB
pulumi/pulumi-go:2.4.0	208.7MB	592MB
pulumi/pulumi-go:2.4.0-ubi	255.07MB	701MB
pulumi/pulumi-nodejs:2.4.0	121MB	341MB
pulumi/pulumi-nodejs:2.4.0-ubi	149.37MB	439MB
pulumi/pulumi-dotnet:2.4.0	213.08MB	598MB
pulumi/pulumi-dotnet:2.4.0-ubi	241.39MB	677MB
pulumi/pulumi-python:2.4.0	106.48MB	308MB
pulumi/pulumi-python:2.4.0-ubi	150.18MB	385MB

Using the Images

Using the new Pulumi images looks very similar to how you might use the CLI locally. Here’s an example of running Pulumi for a typescript project, and the Pulumi SaaS backend:

docker run -e PULUMI_ACCESS_TOKEN=<PULUMI_ACCESS_TOKEN> -v "$(pwd)":/pulumi/projects pulumi-nodejs:latest /bin/bash -c "npm ci && pulumi preview -s dev"

If you’re using one of our cloud backends, you’ll need to specify your cloud provider credentials and login to your selected backend:

docker run -e AWS_REGION=<AWS_REGION> -e AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY> -e AWS_SECRET_ACCESS_KEY=<AWS_ACCESS_SECRET_ACCESS_KEY> -v "$(pwd)":/pulumi/projects pulumi/pulumi-nodejs:2.4.0 /bin/bash -c "pulumi login s3://<s3-bucket> && npm ci && pulumi preview -s <stack-name>"

Pulumi’s intelligent plugin acquisition should find and detect the required resource plugins so you can run your Pulumi program. If you need additional CLI tools like Helm as part of your workflow, we recommend installing these tools as part of your CI/CD pipeline or using these images as a base image to build your own Docker images. Here’s an example of installing Helm in our Go-based Docker image.

# Build container
FROM debian:latest AS build

RUN apt-get update && apt-get install curl -y && \
 curl -L https://get.helm.sh/helm-v3.2.4-linux-amd64.tar.gz |tar xvz && \
 mv linux-amd64/helm /usr/bin/helm && \
 chmod +x /usr/bin/helm

# Runtime container
FROM pulumi/pulumi-go:latest

COPY --from=build /usr/bin/helm /usr/bin/helm

Multiple Base Images

The default operating system for these new images is Debian Buster, but we also publish Images based on RedHat’s Universal Base Image. These images are small and lightweight but also benefit from RedHat’s exceptional security focus. We scanned these images with synk.io and found zero vulnerabilities, which should provide peace of mind when running these Pulumi images.

A Note about Alpine Linux

Many users are fans of Alpine Linux’s small, lightweight footprint and its Docker focused design; however, we’ve made the decision not to publish Alpine based images at this moment. Alpine’s usage of musl libc rather than glibc means that Pulumi doesn’t run without adding additional dependencies, which made it hard to justify introducing this extra source of potential bugs into our already broad surface area. If you’re interested in building and maintaining an Alpine based Pulumi image, we have skeleton Docker files available in the Pulumi GitHub repo.

Give them a spin!

The new images are available from DockerHub; we’d love for you to give them a try! As always, if you find any issues, don’t hesitate to open an issue!

Introducing Pulumi Crosswalk for AWS: The Easiest Way to AWS

Luke Hoban — Mon, 10 Jun 2019 00:00:00 +0000

Some of the code in this post is out of date. See the AWS guides for an updated overview and examples.

Amazon Web Services provides an incredible platform for developers to build cloud-native applications, and is used by millions of customers of all sizes. The building block services that AWS offers enable teams to offload undifferentiated heavy-lifting to AWS. To maximally benefit from these services though, cloud engineering teams must learn how to compose all of these building blocks together to build and deliver their own applications. Today, this is still too hard. Getting from your laptop to a production-ready AWS deployment frequently takes days or weeks instead of minutes or hours. And AWS building block services frequently leave you to re-implement (and re-discover) best-practices instead of providing these as smart defaults.

Pulumi Crosswalk for AWS is a new open source library of infrastructure-as-code components that make it easier to get from zero to production on AWS, easier to adopt AWS best practices by default, and easier to evolve your AWS infrastructure as your application needs mature.

Crosswalk for AWS offers higher-level components for a wide range of the AWS platform - from serverless (Lambda, API Gateway and more) to containers (ECS, Fargate) to Kubernetes (EKS) and across networking (VPCs, SecurityGroups), monitoring (Cloudwatch Dashboards and Alarms) and load balancing (ALB and NLB). Because Crosswalk builds on the primitive building blocks of the AWS platform, you can use 100% of what AWS offers, and can seamlessly move between high-level components and low-level platform primitives, mixing-and-matching as needed.

In some of these domains, there have been successful tools that have helped developers more easily work with one specific aspect of AWS - Serverless Framework for serverless, Docker Compose for ECS, eksctl for EKS. But these tools have traditionally been limited to one specific kind of compute, limiting what users can accomplish, fragmenting development of complete cloud solutions, and leading to sharp cliffs when application needs evolve. Crosswalk for AWS offers the same kind of simpler and more productive developer interface as these tools, but applied uniformly across the entire AWS platform. Simple things are simple, and arbitrarily complex things are possible.

Whether you are starting a new SaaS project at a startup, migrating an enterprise application to cloud-native infrastructure, or delivering a new service as part of an established cloud application, Crosswalk for AWS provides the easiest way to get from zero to production, and to then evolve with your projects’ needs. You can get started with Crosswalk for AWS today!

Note: Crosswalk for AWS projects are authored using the Pulumi infrastructure-as-code tools. Pulumi allows you to define your infrastructure using code. As your infrastructure code evolves, Pulumi makes the minimal required changes to your cloud resources, ensuring that your infrastructure is updated without downtime (if possible).

From Zero to Production And Beyond with Crosswalk for AWS

Serverless (Lambda, API Gateway)

When getting started with a new cloud project, the starting point is often just serving a simple API on the internet. With just a few lines of code and tens of seconds to deploy, Crosswalk for AWS gives us our API.

import * as awsx from "@pulumi/awsx";

const api = new awsx.apigateway.API("api", {
 routes: [{
 method: "GET",
 path: "/",
 eventHandler: async (ev, ctx) => {
 return {
 statusCode: 200,
 body: JSON.stringify(ev),
 };
 }
 }],
})

export const endpoint = api.url;

By building on top of great AWS building blocks like Lambda, API Gateway, IAM and more, we avoid needing to worry about infrastructure, pay nearly zero fixed costs, and gain the ability to iterate quickly. With just a few more lines of code, we can wire up to our own domain, add authorization, provision a database, or chain together a more complex event-driven application.

Containers (ECS, Fargate)

As our needs grow, we might find we need to deploy containers - either custom applications or existing Docker images. Again, just a few lines of code gets our container running in production in AWS.

import * as awsx from "@pulumi/awsx";

// Create the cluster
const cluster = new awsx.ecs.Cluster("cluster");

// Configure a Load Balancer
const alb = new awsx.lb.ApplicationLoadBalancer("lb", {
 securityGroups: cluster.securityGroups,
});
const web = alb.createListener("web", { port: 80, external: true });

// Define the scaled-out Fargate service
const appService = new awsx.ecs.FargateService("app-svc", {
 cluster,
 taskDefinitionArgs: {
 container: {
 image: awsx.ecs.Image.fromPath("app", "./app"),
 portMappings: [ web ],
 },
 },
 desiredCount: 5,
});

export const url = web.endpoint.hostname;

Using ECS, Fargate, ECR and ELB, we get a robust production-ready container deployment - horizontally scaled out, load-balanced, and integrated with a private image repository. With just a few more lines of code, we can add autoscaling, customize our ECS cluster, or wire through advanced container configuration (volumes, environment variables, and more).

Networking (VPC)

To adopt best practices security posture, we may want to move our cluster into a custom VPC, and run our containers in private subnets. We can define and configure our VPC, and then redeploy our containers into this new VPC with ease:

import * as awsx from "@pulumi/awsx";

const vpc = new awsx.ec2.Vpc("vpc", {
 numberOfAvailabilityZones: 3,
});

const cluster = new awsx.ecs.Cluster("cluster", {
 vpc: vpc,
});

// ... same as before ...

The Vpc component builds on best-practices Virtual Private Cloud design patterns based on AWS guidance and documentation. By building in simple defaults for routing, subnet structure, NATs and multi-AZ you can get started quickly without having to re-discover these best practices. And as your needs grow, you can deeply customize and evolve your VPC structure - defining custom CIDR blocks, customizing Internet and NAT Gateways or additional additional private subnets.

Kubernetes (EKS)

As our project continues to evolve, we may want to move our container workloads into Kubernetes using EKS. We can stand up an EKS cluster with just a few lines of code, then customize our cluster and deploy Kubernetes workloads into our cluster.

import * as awsx from "@pulumi/awsx";
import * as eks from "@pulumi/eks";

// Create a VPC for our cluster.
const vpc = new awsx.ec2.Vpc("vpc");

// Create the EKS cluster itself.
const cluster = new eks.Cluster("cluster", {
 vpcId: vpc.id,
 subnetIds: vpc.privateSubnetIds,
 instanceType: "m5.large",
 desiredCapacity: 2,
 minSize: 1,
 maxSize: 2,
 deployDashboard: true,
});

// Export the cluster's kubeconfig.
export const kubeconfig = cluster.kubeconfig;

Building on EKS we get all the benefits of managed Kubernetes paired with the platform capabilities of AWS. With Crosswalk for AWS, we can get started quickly, and then evolve to take advantage of all of these platform features, like customized node groups, private networking, and even deploying Kubernetes YAML and Helm charts to our cluster.

Monitoring (CloudWatch)

Getting our infrastructure up and running in AWS is great, but we also want to be able to monitor it. We can add a few lines to any of the solutions above to define metrics, dashboards, alerting and more to monitor our AWS infrastructure.

import * as aws from "@pulumi/aws";
import * as awsx from "@pulumi/awsx";

// Create a bucket and a function to log all new object created events
const bucket = new aws.s3.Bucket("b");
const subscription = bucket.onObjectCreated("newObject", async (ev) => {
 console.log(JSON.stringify(ev));
});

// Create a CloudWatch Dashobard for our functions invocations
const dashboardName = "funcDashboard";
const dashboard = new awsx.cloudwatch.Dashboard(dashboardName, {
 widgets: [
 new awsx.cloudwatch.LineGraphMetricWidget({
 title: "Lambda invocations",
 width: 14,
 metrics: awsx.lambda.metrics.invocations({
 function: subscription.func, statistic: "Sum", period: 60, }), }), ], });

// Export the URL of the dashboard in the AWS console
export const dashboardUrl =
 `https://${aws.config.region}.console.aws.amazon.com/cloudwatch/home?` +
 `region=${aws.config.region}#dashboards:name=${dashboardName}`;

With CloudWatch being deeply integrated into all AWS services, we can easily build up robust logging, alerting and dashboarding solutions across our AWS infrastructure. With just a few more lines of code we can get logs for our functions and containers, create alarms when we cross critical thresholds, and create rich dashboard layouts all of which will version along with our infrastructure!

Early Feedback

We’ve been working on pieces of Crosswalk for AWS since before we launched Pulumi, and we’re excited to be launching Crosswalk for AWS today to bring these together for all AWS users. Over the last few months, users have built on Crosswalk for AWS for all of the scenarios above and more.

Tableau has used Crosswalk for AWS to accelerate their Kubernetes migration on AWS, building on the networking and EKS capabilities of Crosswalk for AWS.

“We’ve been happily using Pulumi’s EKS support for more than three months now. Our team was looking for an end-to-end solution to tame the complexity of Kubernetes on AWS and ensure we adhere to AWS best practices. Pulumi’s Crosswalk effort has equipped our team to scale far better, our delivery is now automated, and we can now deliver new application and infrastructure features with much faster turn-around, sometimes in just a few hours. Pulumi is a key contributor to our team’s improvement in productivity.” - Pankaj Dhingra, Sr Director, Cloud Engineering, Tableau

Compute Software has used Crosswalk for AWS to go from zero to production, and then to evolve their infrastructure in AWS, all without needing a dedicated cloud infrastructure engineering team.

“We use Crosswalk for AWS with Fargate. It’s been instrumental in getting us into production. Deploying to the cloud is necessarily complex. Crosswalk streamlines the process by exposing the controls you care about, always allowing you to dive deeper when needed.” - Kenny Williams, Co-Founder, Compute Software

We’re excited by the success these teams and many more have already had with Crosswalk for AWS, but even more excited about the potential to truly democratize access to the AWS platform and unlock highly productive cloud development for all kinds of engineering organizations.

What’s Next?

We’re still just scratching the surface of what’s possible with Crosswalk. We’re continuing to evolve the open source projects to simplify additional features of the AWS platform. And we’re also working to bring the same approach to other cloud platforms, including Azure, GCP and Kubernetes.

We believe that making it easier for cloud engineers to develop and deploy natively in the cloud will unlock creativity and empower developers to take advantage of more of the rich capabilities of AWS. We can’t wait to see what you build with Crosswalk!

Crosswalk for AWS is free and open source, and you can get started today.

For more on Crosswalk for AWS see:

Pulumi and Docker: Development to Production

Sean Gilespie — Wed, 15 May 2019 00:00:00 +0000

Here at Pulumi, we’re big fans of Docker: at this point there is little doubt that Docker has completely revolutionized the way that we think about deploying software. However, even in 2019, it’s quite difficult to get Docker containers to production. docker run is great, and we all love it, but unfortunately it’s quite a big leap from docker run to running your container in a production-ready environment.

We recently wrote a blog post about using AWS Fargate to run your docker containers with our open source packages. In this blog post we’re going to focus on another interesting aspect of Pulumi: being able to re-use your infrastructure code for both development and production!

It’s All Code: Composing Docker Containers

In addition to the number of cloud and infrastructure providers that Pulumi supports, Pulumi also supports defining Docker resources in code. Let’s look at this code snippet of Pulumi TypeScript code:

// This program encodes a complete application: a container running Redis Commander,
// and a container running Redis. Redis Commander connects directly with Redis.
//
// In order for the two containers to communicate directly, they must be placed in the
// same network. Before creating the containers themselves, we first create the network
// that will contain both of them.
const network = new docker.Network("net");
// Also before creating a container, we must first obtain a "RemoteImage", which is a reference to an external image
// that is downloaded to the local machine. In this case, we're referring to an image on Docker Hub.
const redisImage = new docker.RemoteImage("redis-image", {
name: "redis:latest",
keepLocally: true, // don't delete the image from the local machine when deleting this resource.
});
// We can create a container using a reference to the name of the image we just downloaded and a reference to the name
// of the network that this container should use.
const redisContainer = new docker.Container("redis", {
image: redisImage.name,
networksAdvanced: [{ name: network.name }],
restart: "on-failure",
});
// We do the same thing for the Redis Commander container.
const redisCommanderImage = new docker.RemoteImage("redis-commander-image", {
name: "rediscommander/redis-commander:latest",
keepLocally: true,
});
const redisCommanderContainer = new docker.Container("redis-commander", {
image: redisCommanderImage.name,
restart: "on-failure",
networksAdvanced: [{ name: network.name }],
envs: [
// Pulumi resources have "output" properties, which are properties that are set upon successful completion of
// the resource operation. These "outputs" are like promises - they can't be used directly but instead must be
// manipulated through use of the `apply` function.
//
// Here, we are using the name of the Redis commander to build an environment variable `REDIS_HOST` that points
// to the network identity of the Redis container we just created.
redisContainer.name.apply(name => `REDIS_HOST=${name}`),
],
// Finally, we expose some ports. Redis Commander listens on port 8081, so we'll map that to external
// port 3000 for easy consumption on the user machine.
ports: [{
internal: 8081,
external: 3000,
}]
});

Here we are looking at a complete Pulumi program that does a bunch of things with Docker:

We create a Docker network named net, which we’ll use to connect two containers together
We pull the redis:latest image from Docker Hub and create a container using it, named redis, which we attach to the network we just created
We pull the rediscommander/redis-commander:latest image from Docker Hub and also create a container using it, named redis-commander, which likewise is attached to the network and exposes some ports on the host machine.

This is fairly nontrivial, but we’ve done it in code right here. Using code we’ve replicated many of the features offered by tools like docker-compose, but without writing a single line of YAML. Running pulumi up with this code results in a working instance of Redis Commander listening on port 3000 on your machine. Nice and simple!

Moving to Production

Orchestrating Docker containers on your local machine while developing is great, but when it comes time to pushing containers to production, you can’t rely on Docker alone anymore. There are a number of excellent container orchestrators out there but there few are as successful as Kubernetes. The way that you launch production workloads in Kubernetes is significantly different than how you would do it using docker run on your own, so it’s often the case that you’d need to write another series of YAML documents to get your application into production.

With Pulumi, we’re just writing code. Since we’re just writing code, we can do exactly what we would do if we were writing application code: abstract!

// Since we're using a general-purpose programming language, we can now use that language to provide multiple
// implementations of the same abstraction. In this case, we define an abstract "Redis" component whose only property is
// that it has some network identity (host) that consumers can connect to and talk to a Redis connection.
export abstract class Redis extends pulumi.ComponentResource {
 public abstract readonly host: pulumi.Output<string>;

 public static create(name: string, args: RedisArgs, opts?: pulumi.ComponentResourceOptions): Redis {
 // Since we are using TypeScript and RedisArgs is the union of argument types for each resource. Since args.type
 // has type "amazon" | "docker" | "kubernetes", the compiler assists us in making sure that we don't
 // accidentally mix up argument types.
 switch (args.type) {
 case "amazon":
 return new AmazonRedis(name, args, opts);
 case "docker":
 return new DockerRedis(name, args, opts);
 case "kubernetes":
 return new KubernetesRedis(name, args, opts);
 }
 }

 constructor(ty: string, name: string, args: RedisArgs, opts?: pulumi.ComponentResourceOptions) {
 super(ty, name, args, opts);
 }
}

export type RedisArgs = DockerRedisArgs | KubernetesRedisArgs | AmazonRedisArgs;

We’ve departed a bit from our previous example, but we’re still writing code. In particular, what we’re doing here is defining a new, abstract, Redis component that takes the Redis container from the previous example and abstracts it away a little bit. This class we’ve created still represents Redis, but completely abstracts away where and how the Redis instance is running. In this case, it can run in any one of three different configurations:

Redis backed by AWS ElastiCache (“amazon”)
Redis running as a Docker container on your machine (“docker”)
Redis running as a Deployment on a Kubernetes cluster (“kubernetes”)

Now, you can use this Redis component completely in the abstract, like this:

const redis = Redis.create("redis", {
 type: "docker",
 network: network,
});

We’re requesting a “docker” container, but we could just as easily switch this out for “amazon” and “kubernetes”, and suddenly our Redis workload is transparently deployed in different ways, all without disrupting our development environment!

Pulumi: Infrastructure as Software

We often say on this blog that Pulumi is “infrastructure as code”, and that sentence is definitely true, but I prefer calling it “infrastructure as software” instead. The distinction is subtle, but in my mind Pulumi brings to the realm of infrastructure the variety of tools we already use for software engineering:

Abstraction, encapsulation, and code reuse for infrastructure and applications
Testing, both unit and integration
IDEs and tools for detecting errors extremely early in a developer’s inner loop, instead of at deployment time

Pulumi is open source, free to use, and works today with a variety of clouds and bring a little more software and less code into your infrastructure! If you’d like to see more about this particular code demo, check out my DockerCon EU 2018 talk where I dive into this in detail. The code for this post and the talk are in this repository.

Pulumi Blog: Docker

105 Ways to Run Containers: The Cloud Container Iceberg

Constraints

Above the iceberg – The usual suspects

On the iceberg – The slightly less obvious

The kubernetes multiverse – Because one Universe of k8s wasn’t enough

Below the water – Kubernetes everywhere – Let a thousand K8s bloom

Middle of the iceberg – Serverless and function containers – Now you see me, now you don’t

Bottom of the iceberg – Specialized and hybrid platforms – The swiss army knife of container hosting

Below the iceberg – Containers on the edge of reason

The abyss – Where containers fear to tread

Beyond the abyss

Managing your container zoo with pulumi

The final word

Improving Pulumi’s Docker Images

Updating the Default Language Versions

Setting the Language Version in Pulumi Deployments

Additional Tools

Conclusion

Introducing The New Docker Build Provider

A brief history

Getting started

Migrating from docker.Image to docker_build.Image

Migrating from Docker provider v3

Migrating from Docker provider v4

Conclusion

Local Testing With Pulumi

Listening in at Zephyr HQ

Using Pulumi for the inner dev loop

Try this out yourself

Fast Docker Image Builds with Pulumi

TL;DR

What actually moves the needle

How does Pulumi build Docker images?

Why are my Docker builds slow?

How do I enable BuildKit and registry caching in Pulumi?

With the Docker Build provider (recommended)

With the Docker provider (docker.Image)

How do I write a Dockerfile that builds fast?

How do I build multi-platform images with Pulumi?

How do I see Docker build output in Pulumi?

How do I migrate an older docker.Image program?

Getting started

Cloud Systems: Deploying to Amazon ECS

Elastic Container Service

Prerequisites:

Configuring Amazon ECS

Deploying a Dockerized Flask Application to ECS

Cloud Systems: Containerizing a Website

Containers

Prerequisites:

Expanding the Website

Templating

Dockerizing our Website

How to Build a Container Registry

Container registry offerings

Build it

Learn more

Build and publish container images to any cloud with Infrastructure as Code

Approach

Prepare a Container Registry

Amazon Elastic Container Registry (ECR)

Create a New Project

Provision an ECR Repository

Authenticate with Temporary ECR Access Token

Alternatively, Authenticate with ECR Credential Helper

Learn More About ECR

Azure Container Registry (ACR)

Create a New Project

Provision a New ACR Registry

Authenticate with Admin Account

Alternatively, Authenticate with ActiveDirectory Service Principal

Learn More About ACR

Google Container Registry (GCR)

Create a New Project

Ensure Your GCR Registry is Ready

Authenticate with the Google Cloud SDK

Learn More About GCR

DigitalOcean Container Registry

Create a New Project

With the Docker provider (`docker.Image`)

How do I migrate an older `docker.Image` program?