Saving to Cloud Pods

In the previous section you learned how to save a snapshot of the emulator’s state to a local file, then to re-load the snapshot into a different emulator instance. However, when working in a team environment, it’s important to have a standard mechanism for sharing snapshot files across your team, and for managing updates as new versions are published.

LocalStack provides the web-based Cloud Pods repository for exactly this purpose, accessible only to the users in your organization. Snapshots can be generated by an emulator instance, then automatically published to your Cloud Pods repository. From there, snapshots can be loaded back into an emulator instance, either on a desktop environment or a CI environment.

Each organization has their own private Cloud Pods repository, securely managed in LocalStack’s cloud. Each user or organization is allocated a dedicated and isolated Amazon S3 bucket. The LocalStack CLI utilizes secure S3 presigned URLs to directly interface with the S3 bucket, bypassing the need to transmit the snapshot files through LocalStack Platform APIs.

Using the lstk CLI

You can save and load the snapshots to/from your Cloud Pods repository using the lstk snapshot command.

lstk snapshot --help

Manage emulator snapshots

Usage: lstk snapshot [flags]

Commands:
  list        List Cloud Pod snapshots available on the LocalStack platform
  load        Load a snapshot into the running emulator
  remove      Delete a cloud snapshot from the LocalStack platform
  save        Save a snapshot of the emulator state
  show        Show metadata for a cloud snapshot

Saving a snapshot to Cloud Pods

The command for saving a snapshot to Cloud Pods is similar to saving locally, but instead of a file name, provide the pod: prefix followed by a valid Pod name.

lstk snapshot save pod:sample-application

✔︎ Snapshot saved to pod:sample-application
• Version: 1
• Services: s3, sns, sqs, lambda
• Size: 64.2 KB

Optionally, you can include a message with the saved snapshot using the --message flag.

You can access the list of available Cloud Pods for both you and your organization by utilizing the list command:

localstack pod list

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                         ┃ Max Version ┃ Last Change         ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ s3-test                      │ 1           │ 2024-01-04 11:03:00 │
└──────────────────────────────┴─────────────┴─────────────────────┘

With the save command you can create multiple versions of a Cloud Pod. For instance, let us create a SQS queue and second version of s3-test.

awslocal sqs create-queue --queue-name test-queue

localstack pod save s3-test

Cloud Pod `s3-test` successfully created ✅
Version: 2
Remote: platform
Services: s3,sqs

Note

Permission on Cloud Pods are assigned at organization level. This means that every individual in the organization can view, load, and delete Cloud Pods created by other team members. Similarly, everyone can save a new version of a Cloud Pod on top of a Pod originally created by someone else.

Pull your Pod state

On a separate machine, start LocalStack while ensuring the Auth Token is properly configured. Then, retrieve the previously created Cloud Pod by employing the load command, specifying the Cloud Pod name as the first argument:

localstack pod load s3-test

Cloud Pod s3-test successfully loaded

You can examine the S3 buckets within the Cloud Pod:

awslocal s3 ls s3://test/

2022-10-04 22:33:54         12 hello-world

You can also load a specific version by appending a version number to the pod name after a colon. If not specified, the latest version will be loaded.

localstack pod load s3-test:1

Cloud Pod s3-test:1 successfully loaded

After loading the Cloud Pod’s content, you can use the state inspect command to observe the state of the running LocalStack instance.

TBD: lstk snapshot show

lstk status

xxx

TBD: lstk snapshot remove

For comprehensive instructions, navigate to our lstk CLI Guide.

Note

The snapshots stored in a Cloud Pod may not remain compatible if used with a different version of LocalStack. LocalStack applies snapshot compatibility rules to block loading snapshots known to be incompatible with the running LocalStack version.

Using the LocalStack Console

The LocalStack Web Application enables you to :

• Browse your Cloud Pods and access your version history.
• Export & import Cloud Pods to and from LocalStack instances.
• View Cloud Pods metadata, resources, regions, and version history.

Browse Cloud Pods

Cloud Pods Browser allows you to view, manage, and explore your Cloud Pods through the LocalStack Web Application. With Cloud Pods, you can have individual or shared ownership of a snapshot of your LocalStack instance.

The Cloud Pods Browser provides the following functionalities:

• View Cloud Pods: View all Cloud Pods saved by you or your organization.
• View Versions: View the version history of a Cloud Pod and access previous versions of specific Cloud Pods by clicking on the Cloud Pod’s name.
• View Cloud Pod Details: View the details of a specific Cloud Pod version by clicking on the version.
• View Cloud Pod storage: View the organization storage usage and user storage usage on top of the Cloud Pods Browser.
• Delete Cloud Pod: Delete a Cloud Pod by selecting the Cloud Pod and navigating to the Actions button, followed by Delete.

View Cloud Pods metadata

You can view Cloud Pods metadata by selecting any Cloud Pod in the Cloud Pods Browser. The metadata includes details such as:

• The user who created the Cloud Pod
• The creation timestamp
• The LocalStack version used to create the Cloud Pod
• The size of the Cloud Pod
• The service resources contained in the Cloud Pod

You can view detailed information within a Cloud Pod, including available resources, categorized services with configurations, and quick access to resource identifiers and endpoints—all without loading the Cloud Pod into your LocalStack runtime.

To save metadata with resource details in the Cloud Pod, ensure your LocalStack container is running and save the Cloud Pod with ENABLE_POD_RESOURCES=1. Cloud Pods saved without this configuration enabled will not display granular details.

Export & Import Cloud Pods

You can export and import your LocalStack infrastructure state as a Cloud Pod using the LocalStack Web Application. This feature is particularly useful when you need to use a user-friendly interface to manage your Cloud Pods, without the need to interact with the CLI.

Export the State

To export the state, follow these steps:

1. Navigate to the Cloud Pod tab within the Export/Import State page.
2. Create AWS resources locally as needed.
3. Enter the Pod name and toggle between the New Pod and Existing Pod options.
4. Enter the services to save resources for. By default, all available service resources are saved.
5. Click on Create New Pod.

A new Cloud Pod will be created and will be available for import into another LocalStack instance. You can check out the list of available Cloud Pods in the Cloud Pod page.

Import the State

To import the state, follow these steps:

1. Navigate to the Cloud Pod tab within the Export/Import State page.
2. Choose the Cloud Pod from the drop-down list.
3. Click on Load State From Pod.

To confirm the successful injection of the container state, visit the respective Resource Browser for the services and verify the resources.

Auto Loading Cloud Pods

In addition to loading Cloud Pods through the Command-Line Interface (CLI) or the Web Application, you can configure the automatic loading of one or more Cloud Pods upon the startup of the LocalStack container.

Environmental variables

To automatically load a Cloud Pod at startup, utilize the AUTO_LOAD_POD configuration variable.

AUTO_LOAD_POD can accept multiple Cloud Pod names separated by commas. To autoload multiple Cloud Pods, such as foo-pod and bar-pod, use: AUTO_LOAD_POD=foo-pod,bar-pod. The order of Cloud Pods in AUTO_LOAD_POD dictates their loading sequence. When autoloading multiple Cloud Pods, later pods might overwrite the state of earlier ones if they share the same service, account, and region.

LocalStack CLI

AUTO_LOAD_POD=foo-pod localstack start

Docker Compose

services:
  localstack:
    container_name: "localstack-main"
    image: localstack/localstack-pro
    ports:
      - "127.0.0.1:4566:4566"
      - "127.0.0.1:4510-4559:4510-4559"
    environment:
      - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?}
      - DEBUG=1
      - AUTO_LOAD_POD=foo-pod,bar-pod
    volumes:
      - "./volume:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

Docker

docker run \
  -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \
  -e AUTO_LOAD_POD=foo-pod \
  -v ./volume:/var/lib/localstack \
  -p 4566:4566 \
  localstack/localstack-pro

Configuration file

LocalStack allows for the use of configuration files to automatically load Cloud Pods during startup.

Within the container, LocalStack searches through the /etc/localstack/init-pod.d directory for two file types: zip files created using the localstack state export command, and txt files, where each line represents the name of a Cloud Pod.

Take the following example of a project layout:

• docker-compose.yml
• Directoryinit-pods.d

  • pod-list.txt
  • my-state.pod.zip

The pod-list.txt contains the following:

foo-pod
bar-pod

LocalStack, upon mounting init-pods.d to the appropriate location, will sequentially load foo-pod and bar-pod as listed in pod-list.txt, and then proceed to load my-state.pod.zip.

The docker compose file for correctly mounting init-pods.d will look like:

services:
  localstack:
    container_name: "localstack-main"
    image: localstack/localstack-pro
    ports:
      - "127.0.0.1:4566:4566"
      - "127.0.0.1:4510-4559:4510-4559"
    environment:
      - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?}
      - DEBUG=1
    volumes:
      - "./volume:/var/lib/localstack"
      - "./init-pods.d:/etc/localstack/init-pods.d"

End-to-End Encryption Enterprise

Cloud Pods artifacts are stored in S3 buckets when using the LocalStack platform as the storage remote. By default, Amazon S3 encrypts all objects before saving them on disks, while the opposite operation happens at download time. This ensures encryption at rest for Cloud Pods.

When this is not enough, LocalStack also offers end-to-end encryption for enterprise customers as a preview feature. To activate this feature, make sure to start LocalStack with the POD_ENCRYPTION environment variable set to 1.

The next step is to generate a passphrase used to encrypt and decrypt the Cloud Pods’ artifacts. We advise to create a strong passphrase by using the openssl utility, e,g.:

openssl rand --base64 32
# 3X03eU5pgoejObUR+Y8I4QjbjeGEKjDcmVFd0FU5pCg=

Users should treat the generated passphrase as a secret and they are responsible for securely sharing it within the organization. The generated secret can now be provided as an option to the save command when creating an encrypted Cloud Pod.

localstack pod save my-secret-pod --secret 3X03eU5pgoejObUR+Y8I4QjbjeGEKjDcmVFd0FU5pCg=

Loading an encrypted Cloud Pod would require a similar load command:

localstack pod load my-secret-pod --secret 3X03eU5pgoejObUR+Y8I4QjbjeGEKjDcmVFd0FU5pCg=

Encryption with PGP keys

We also offer the option of using PGP keys to encrypt and decrypt Cloud Pods. The process is the following:

• Customers would have to export both their private and public keys into two files, private.pgp and public.pgp respectively.
• These files need to be mounted in a specific pods.keys.d folder when starting LocalStack, i.e., localstack start -v $PWD/pods.keys.d:/etc/localstack/pods.keys.d.
• The secret option passed to the save and load command corresponds to the passphrase needed to import the private key into the LocalStack runtime.

Limitations

• Both browsing the Cloud Pod content via the UI and loading Cloud Pods into ephemeral instances are currently not supported for encrypted Cloud Pods.
• It is not possible to have both encrypted and non-encrypted versions for a Cloud Pod. Encryption is set at the moment of the creation and it cannot be changed.

Troubleshooting

Unable to obtain Auth Token

When you try to save a Cloud Pod and see the error in LocalStack logs like this:

localstack.cli.exceptions.CLIError: Failed to create Cloud Pod sample-pod ❌ - Unable to obtain auth token (code 401) - please log in again.

It would be good to check if you have outdated authentication credentials (bearer token from a previous LocalStack login) in the remotes.yaml file for cloud pods. You have two options to fix this:

1. Run another localstack auth login command.
2. Find the remotes.yaml file in the <localstack_volume> directory on your machine and delete the file, or at least remove the "default" entry from it.

Additionally, if there is a ~/.localstack/auth.json file in your home directory, delete it as well if it still exists.

License not found

When you try to save a Cloud Pod and see the license.not_found error in LocalStack logs like this:

lsmulti-localstack  | 2024-03-15T13:06:16.358  WARN --- [functhread31] l.p.remotes.remotes        : Failed to register pod sample-pod: {"error": true, "message": "licensing.license.not_found"}

To fix this, clear the LocalStack cache directory and restart the LocalStack instance before trying to save the Cloud Pod again. You can find the cache directories at:

• /Users/localstack/Library/Caches/localstack
• /Users/localstack/Library/Caches/localstack-cli

Adjust the path based on your operating system.

SSL Certificate verification failed

If you get an SSL certificate verification error while trying to save a Cloud Pod, as shown below:

An error occurred while checking remote management for pod "cloud-pod-product-app": "MyHTTPSConnectionPool(host='api.localstack.cloud', port=443): Max retries exceeded with url: /v1/cloudpods/cloud-pod-product-app (Caused by SSLError(SSLCertVerificationError(1, "[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: Hostname mismatch, certificate is not valid for 'api.localstack.cloud'. (_ssl.c:1006)")))"

Check if your machine’s clock is set incorrectly or if the certificate store is outdated. This error can also occur if you use localstack as LOCALSTACK_HOST. In this case, the DNS incorrectly resolves api.localstack.cloud to localhost, causing a certificate mismatch.

InvalidAccessKeyId during CreateBucket API call

You may see this error:

An error occurred (InvalidAccessKeyId) when calling the CreateBucket operation: The AWS Access Key Id you provided does not exist in our records.

This usually means you’re using temporary AWS credentials, but AWS_SESSION_TOKEN is missing from the environment.

To fix this, ensure that you export the AWS_SESSION_TOKEN environment variable:

export AWS_SESSION_TOKEN=...

Then, add session_token to the pod remote add URL:

localstack pod remote add s3-storage-aws 's3://ls-pods-bucket-test/?access_key_id={access_key_id}&secret_access_key={secret_access_key}&session_token={session_token}'

If you’re still unable to connect to the S3 bucket, add the bucket hostname to the upstream DNS resolution list:

DNS_NAME_PATTERNS_TO_RESOLVE_UPSTREAM=ls-pods-bucket-test.s3.amazonaws.com/

For more details, see the Skip LocalStack DNS Resolution section.