Connect your tools

Before you start: pogi is running (pogi start). The commands below find it at http://localhost:7644. If it runs on another port, pass --endpoint to client commands, or set POGI_ENDPOINT.

SDKs and CLIsCopy Anchor Link

pogi env prints the settings that point every cloud tool at pogi.

1. Load them into your shell. Pick the tab for your shell:

eval "$(pogi env)"

2. Use your tools as usual. The sections below say what pogi env sets for each cloud.

AWSCopy Anchor Link

pogi env sets AWS_ENDPOINT_URL, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (both test), AWS_DEFAULT_REGION and AWS_REGION. Every current AWS SDK and the AWS CLI read AWS_ENDPOINT_URL, so your code does not change. This Go program lists buckets with no pogi-specific code:

package main

import (
	"context"
	"fmt"

	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
	ctx := context.Background()
	cfg, err := config.LoadDefaultConfig(ctx) // reads AWS_ENDPOINT_URL and the test credentials
	if err != nil {
		panic(err)
	}
	out, err := s3.NewFromConfig(cfg).ListBuckets(ctx, &s3.ListBucketsInput{})
	if err != nil {
		panic(err)
	}
	for _, b := range out.Buckets {
		fmt.Println(*b.Name)
	}
}

With a bucket called demo, it prints:

demo

To run the AWS CLI without loading the variables, use pogi aws. It needs the AWS CLI installed.

pogi aws s3 ls

Google CloudCopy Anchor Link

pogi env sets STORAGE_EMULATOR_HOST, PUBSUB_EMULATOR_HOST, FIRESTORE_EMULATOR_HOST, DATASTORE_EMULATOR_HOST and, for the Firebase Admin SDK, FIREBASE_AUTH_EMULATOR_HOST. The client libraries read them. It also sets the gcloud settings (CLOUDSDK_API_ENDPOINT_OVERRIDES_*, project pogi), so gcloud talks to pogi.

AzureCopy Anchor Link

pogi env sets AZURE_STORAGE_CONNECTION_STRING (Azurite ports 10000 to 10002), and COSMOS_ENDPOINT, COSMOS_KEY and AZURE_KEYVAULT_URL on the HTTPS port. HTTPS services use pogi's own certificate authority (CA). Run pogi cert to see where it is and how to trust it.

S3 with bucket names in the hostCopy Anchor Link

Some code needs the bucket in the host name (<bucket>.s3.aws.localhost).

1. Start pogi with a host name:

   Copy Text

   pogi start --hostname aws.localhost

2. Print matching settings:

   Copy Text

   pogi env --hostname aws.localhost

   export AWS_ENDPOINT_URL="http://aws.localhost:7644"
   export AWS_ENDPOINT_URL_S3="http://s3.aws.localhost:7644"
   …

   To load them, run eval "$(pogi env --hostname aws.localhost)".

pogi doctor tells you whether *.localhost names resolve on your machine.

TerraformCopy Anchor Link

pogi tf prints a provider block with every endpoint pointed at pogi.

1. Write it next to your own files. Terraform loads *_override.tf files over your own settings, so your configuration stays as it is:

   Copy Text

   pogi tf > pogi_override.tf

   The file starts like this:

   Copy Text

   # Generated by "pogi tf": point the AWS provider at pogi.
   provider "aws" {
     region                      = "us-east-1"
     access_key                  = "test"
     secret_key                  = "test"
     skip_credentials_validation = true
     skip_metadata_api_check     = true
     skip_requesting_account_id  = false
     s3_use_path_style           = true

2. Run Terraform:

   Copy Text

   terraform init
   terraform apply

For the other clouds:

pogi tf --cloud gcp > pogi_override.tf
pogi tf --cloud azure > pogi_override.tf

The azurerm provider needs HTTPS. The Azure output starts with comments that show how to run Terraform in a container that trusts pogi's CA.

CDKCopy Anchor Link

No wrapper is needed, and custom resources work, including the CDK provider framework.

1. Set AWS_ENDPOINT_URL and the test credentials in your shell:

   Copy Text

   eval "$(pogi env)"

2. Run pogi lambda-sdks once. It gives native Lambda functions the AWS SDKs that real Lambda runtimes include: the JavaScript v3 SDK from npm and boto3 from pip, in pogi's data folder. You need Node.js and Python on your machine.

   Copy Text

   pogi lambda-sdks

3. Bootstrap and deploy:

   Copy Text

   cdk bootstrap
   cdk deploy

Go testsCopy Anchor Link

1. Start pogi inside the test, and set the environment for the code under test:

   Copy Text

   srv := pogi.Start(t)  // in-process on a random port, cleaned up with the test
   srv.Setenv(t)         // AWS_ENDPOINT_URL, *_EMULATOR_HOST, Azure settings for code under test

2. Build your client as usual. It now points at pogi:

   Copy Text

   cfg, _ := config.LoadDefaultConfig(ctx)

pogi.Start(t) runs everything inside the test process, with no container. With pogi.Start(t, cfg) and cfg, _ := pogi.LoadConfig("testdata/pogi.yaml"), it also creates what the pogi.yaml file lists.

With Testcontainers, run the ghcr.io/nrndev/pogi image, expose port 7644, and wait for the log line Ready. or for /_localstack/health.

Check that it worksCopy Anchor Link

1. Check that pogi is up:

   Copy Text

   pogi status

2. Follow every call your tools make:

   Copy Text

   pogi logs -f

If a call does not show up, your tool is not using the endpoint from pogi env. See Troubleshoot.

See alsoCopy Anchor Link

• CLI
• Configuration
• Install pogi
• Troubleshoot