Want to learn about running containers in Lambda? Join our free hands-on workshop. Register Now

Pulumi API

The Pulumi API is one of the components required for self-hosting Pulumi in your organization’s environment. It provides the necessary APIs for both the CLI and the Console.

Prerequisites

  • Provide a server or virtual machine to install and run the Pulumi components (see Minimum System Requirements below).
  • Provide a persistent volume for the service to store checkpoint objects.
  • Provider a persistent volume for the MySQL data (optional if you are providing your own DB.)
  • If you are providing your own DB instance, ensure that it is accessible within the same Docker network that the service and the UI containers will be running in.
    • The default DB endpoint is pulumi-db:3306. If you wish to change this, set PULUMI_LOCAL_DATABASE_NAME and PULUMI_LOCAL_DATABASE_PORT accordingly (see Script Variables.)
    • If you do not create this network prior to running run-ee.sh, it will create only a bridged network on your local host. Ensure that the DB can be accessed by the API service container.
  • Provide an external load balancer with TLS termination.

Minimum System Requirements

TypePropertiesNotes
Compute2 CPU cores w/ 8 GB memory
Storage20GB SSDFor MySQL data.

Note: By default, the installation uses a single data path via PULUMI_DATA_PATH to map both the SQL data volume and the object storage path. Specify a volume for the db container as required.
Storage200GB SSDFor Object Storage.

Note: By default, the installation uses a single data path via PULUMI_DATA_PATH to map both the SQL data volume and the object storage path. A dedicated path can be set via env var PULUMI_LOCAL_OBJECTS for the api container.

Note: The storage recommendations for the Object Storage can be lesser than 200GB depending on your organization size and the expected usage.

What’s In The Container?

The API service is a Go-based application. This is a single binary application that has all of the dependencies it needs in order to run.

Server

This container runs an HTTP server which provides the APIs needed by the Console and the CLI. By default this container will serve using port 8080 over standard HTTP. If TLS is configured the server will instead serve over port 8443 using HTTPS.

Primary Environment Variables

Variable NameDescription
PULUMI_LICENSE_KEYThe license key value. A JWT string.

Note: Be sure to enclose the value in single-quotes.
PULUMI_DATABASE_ENDPOINTThe database server endpoint in the format host:port. This should be a MySQL 5.6 server.
PULUMI_DATABASE_NAMEThe name of the database on the database server.
PULUMI_API_DOMAINThe internet or network-local domain using which the API service can be reached, e.g. api.pulumi.com. Default is localhost:8080.
PULUMI_CONSOLE_DOMAINThe internet or network-local domain using which the Console can be reached, e.g. app.pulumi.com. Default is localhost:3000.
PULUMI_LOCAL_OBJECTSFolder path for persisting state for stacks. Ensure that this path is highly available, and backed-up regularly.

Other Environment Variables

Variable NameDescription
PULUMI_OBJECTS_BUCKETS3 bucket name for persisting state for stacks.

Note: Only used if hosted on AWS.
RECAPTCHA_SECRET_KEYreCAPTCHA secret key for self-service password reset. Create a site key and a secret key from Google.
SAML_CERTIFICATE_PUBLIC_KEYPublic key used by the IdP to sign SAML assertions. Learn how to set SAML_CERTIFICATE_PUBLIC_KEY.
SAML_CERTIFICATE_PRIVATE_KEYPrivate key used by Pulumi to validate the SAML assertions sent by the IdP. Learn how to set SAML_CERTIFICATE_PRIVATE_KEY.
GITHUB_OAUTH_ENDPOINTUsed for GitHub API calls.
GITLAB_OAUTH_ENDPOINTUsed for GitLab API calls.

TLS Environment Variables

API Service

The service is configurable to serve the API using TLS. The following environment variables are all required in order to enable TLS. The values of the environment variables may either be a filepath or the actual value of the entity. If these variables are set, the service will be served over HTTPS (i.e using TLS) using port 8443. If the following variables are not set the service will default to serving over HTTP using port 8080.

Variable NameDescription
API_TLS_CERTIFICATEThe TLS certificate. The certificate must be supplied in X.509 format and must be PEM encoded.
API_TLS_PRIVATE_KEYThe private key associated with the TLS certificate. The private key must be PEM encoded.
API_MIN_TLS_VERSIONThe minimum version of TLS to use when serving the API (must be in <major>.<minor> format, e.g. 1.2).

Note: Self-signed certificates may be used to configure TLS in the event the need for a trusted entity is not necessary. A self-signed cert and private key may be generated using OpenSSL. The following command uses OpenSSL to generate a self-signed certificate. This example will output two files, the certificate (cert.pem) and the private key (key.pem) used to sign it.

openssl \
  req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
  -days { days_unitl_expiration } -nodes -subj "/CN={ common_name }"

Database Connections

API Service

The service is configurable to enable connections to the backend SQL database over TLS. The following environment variables are all required to connect to the database using TLS. If these variables are set the service will establish connections to the database using TLS, otherwise the service will default to connecting without TLS. The same ports will be used for communication to the database regardless of whether TLS is configured or not.

Variable NameDescription
DATABASE_CA_CERTIFICATEThe CA certificate used to establish TLS connections with the database. This certificate must be PEM encoded. This must be set to the value of the certificate itself and not a filepath to the location of the certificate file.
DATABASE_MIN_TLS_VERSIONThe minimum TLS version to use for database connections (must be in <major>.<minor> format, e.g. 1.2).
Migrations

The database migrations container is configurable to enable connections to the database over TLS. To use TLS, the following environment variable must be set. The default is to not use TLS.

Variable NameDescription
DATABASE_CA_CERTIFICATEThe CA certificate used to establish TLS connections with the database. This certificate must be PEM encoded. This must be set to the value of the certificate itself and not a filepath to the location of the certificate file.
MYSQL_ROOT_USERNAMEThe root username to log in to the MySQL database. Defaults to root.
MYSQL_ROOT_PASSWORDThe root user password to log in to the MySQL database.
MYSQL_ALLOW_EMPTY_PASSWORDSet to true to allow the container to be started with a blank password for the root user.
PULUMI_DATABASE_ENDPOINTThe database server endpoint in the format host:port. This should be a MySQL 5.6 server.
PULUMI_DATABASE_PING_ENDPOINTThe database server endpoint to ping for availability before login.
RUN_MIGRATIONS_EXTERNALLYRequest for migrations to be run against an external database.