diff --git a/astro.config.mjs b/astro.config.mjs index 6095951a4..6ab634cec 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -475,10 +475,6 @@ export default defineConfig({ label: 'Overview', slug: 'aws/developer-tools/running-localstack', }, - { - label: 'LocalStack CLI', - slug: 'aws/developer-tools/running-localstack/localstack-cli', - }, { label: 'lstk CLI', slug: 'aws/developer-tools/running-localstack/lstk', @@ -491,6 +487,10 @@ export default defineConfig({ label: 'LocalStack Desktop', slug: 'aws/developer-tools/running-localstack/localstack-desktop', }, + { + label: 'Deprecated LocalStack CLI', + slug: 'aws/developer-tools/running-localstack/localstack-cli', + }, ], }, { diff --git a/public/_redirects b/public/_redirects index 06a227afc..122b3f41f 100644 --- a/public/_redirects +++ b/public/_redirects @@ -30,7 +30,7 @@ /applications/appsync-graphql-apis-for-dynamodb-and-rds-aurora-postgresql/ https://github.com/localstack-samples/sample-appsync-graphql-api 301 /user-guide/aws/cloudfront/ /aws/services/cloudfront/ 301 /applications/note-taking-application-using-aws-sdk-for-javascript/ https://github.com/localstack-samples/sample-notes-app-dynamodb-lambda-apigateway 301 -/user-guide/state-management/export-import-state/ /aws/developer-tools/snapshots/export-import-state/ 301 +/user-guide/state-management/export-import-state/ /aws/developer-tools/snapshots/saving-snapshots-locally/ 301 /references/coverage/coverage_s3control/ /aws/services/s3/ 301 /references/custom-tls-certificates/ /aws/developer-tools/security-testing/custom-tls-certificates/ 301 /references/coverage/coverage_codecommit/ /aws/services/codecommit/ 301 @@ -38,13 +38,13 @@ /user-guide/tools/testing-utils/ /aws/customization/integrations/localstack-sdks/testing-utils/ 301 /user-guide/aws/codedeploy/ /aws/services/codedeploy/ 301 /references/coverage/coverage_serverlessrepo/ /aws/services/serverlessrepo/ 301 -/user-guide/aws/resource_groups/ /aws/services/resource_groups/ 301 +/user-guide/aws/resource_groups/ /aws/services/resource-groups/ 301 /references/coverage/coverage_glue/ /aws/services/glue/ 301 /user-guide/aws/ssm/ /aws/services/ssm/ 301 /references/coverage/coverage_sts/ /aws/services/sts/ 301 /academy/localstack-101/course-overview/ https://www.youtube.com/watch?list=PLTew28KOwGxPqbkFiW518eeIfiV495bm0&v=VLL-BI1AWcc&feature=youtu.be 301 /user-guide/aws/iotwireless/ /aws/services/iotwireless/ 301 -/user-guide/integrations/sdks/python/ /aws/connecting/aws-sdks/net/python/ 301 +/user-guide/integrations/sdks/python/ /aws/connecting/aws-sdks/python-boto3/ 301 /user-guide/integrations/crossplane/ /aws/connecting/infrastructure-as-code/crossplane/ 301 /references/coverage/coverage_elbv2/ /aws/services/elb/ 301 /user-guide/integrations/openshift/ /aws/customization/kubernetes/openshift/ 301 @@ -75,7 +75,6 @@ /references/coverage/coverage_kms/ /aws/services/kms/ 301 /applications/step-up-authentication-using-amazon-cognito/ https://github.com/localstack-samples/sample-cdk-cognito-dynamodb-api-gateway 301 /references/coverage/coverage_athena/ /aws/services/athena/ 301 -/user-guide/aws/mediastore/ /aws/services/mediastore/ 301 /references/coverage/coverage_fis/ /aws/services/fis/ 301 /user-guide/aws/logs/ /aws/services/logs/ 301 /academy/localstack-deployment/infra-cloudformation/ https://www.youtube.com/watch?list=PLTew28KOwGxPdtdW00WNXZLZnstvRQyTF&v=K0OgQ5eq588&feature=youtu.be 301 @@ -86,7 +85,6 @@ /references/credentials/ /aws/connecting/credentials/ 301 /references/coverage/coverage_elasticbeanstalk/ /aws/services/elasticbeanstalk/ 301 /user-guide/web-application/instance-management/ /aws/connecting/console/instance-management/ 301 -/references/coverage/coverage_qldb/ /aws/services/qldb/ 301 /academy/localstack-deployment/iam-policy-stream/ https://www.youtube.com/watch?list=PLTew28KOwGxPdtdW00WNXZLZnstvRQyTF&v=TOBLG2Z6xAM&feature=youtu.be 301 /references/cross-account-access/ /aws/customization/advanced/cross-account-access/ 301 /tutorials/reproducible-machine-learning-cloud-pods/ /aws/tutorials/reproducible-machine-learning-cloud-pods/ 301 @@ -120,12 +118,11 @@ /user-guide/localstack-enterprise/single-sign-on/azure-ad/ /aws/organizations-admin/sso/azure-ad/ 301 /user-guide/tools/localstack-desktop/ /aws/developer-tools/running-localstack/localstack-desktop/ 301 /references/coverage/coverage_es/ /aws/services/es/ 301 -/user-guide/integrations/sdks/javascript/ /aws/connecting/aws-sdks/net/javascript/ 301 +/user-guide/integrations/sdks/javascript/ /aws/connecting/aws-sdks/javascript/ 301 /references/coverage/coverage_iam/ /aws/services/iam/ 301 -/user-guide/tools/localsurf/ /aws/customization/networking/localsurf/ 301 +/user-guide/tools/localsurf/ /aws/customization/networking/ 301 /user-guide/extensions/extensions-library/ /aws/customization/integrations/extensions/extensions-library/ 301 /tutorials/ecs-ecr-container-app/ /aws/tutorials/ecs-ecr-container-app/ 301 -/references/coverage/coverage_elastictranscoder/ /aws/services/elastictranscoder/ 301 /user-guide/aws/feature-coverage/ /aws/services/ 301 /user-guide/aws/lambda/ /aws/services/lambda/ 301 /references/iam-coverage/ /aws/developer-tools/security-testing/iam-coverage/ 301 @@ -137,12 +134,11 @@ /user-guide/aws/s3/ /aws/services/s3/ 301 /user-guide/lambda-tools/vscode-extension/ /aws/connecting/ides/vscode-extension/ 301 /user-guide/chaos-engineering/ /aws/developer-tools/chaos-engineering/ 301 -/persistence/supported/ /aws/developer-tools/snapshots/persistence/ 301 +/persistence/supported/ /aws/developer-tools/snapshots/service-coverage/ 301 /user-guide/aws/ce/ /aws/services/ce/ 301 /user-guide/aws/kinesisanalyticsv2/ /aws/services/kinesisanalyticsv2/ 301 /user-guide/state-management/cloud-pods/ /aws/developer-tools/snapshots/cloud-pods/ 301 /references/coverage/coverage_transcribe/ /aws/services/transcribe/ 301 -/references/coverage/coverage_mediastore-data/ /aws/services/mediastore/ 301 /user-guide/aws/route53/ /aws/services/route53/ 301 /user-guide/aws/config/ /aws/services/config/ 301 /references/coverage/coverage_identitystore/ /aws/services/identitystore/ 301 @@ -158,7 +154,7 @@ /developer-hub/ /aws/sample-apps/ 301 /references/coverage/coverage_firehose/ /aws/services/firehose/ 301 /user-guide/aws/verifiedpermissions/ /aws/services/verifiedpermissions/ 301 -/references/coverage/coverage_kinesisanalytics/ /aws/services/kinesisanalytics/ 301 +/references/coverage/coverage_kinesisanalytics/ /aws/services/kinesisanalyticsv2/ 301 /user-guide/aws/sns/ /aws/services/sns/ 301 /user-guide/tools/aws-replicator/ /aws/developer-tools/aws-replicator/ 301 /user-guide/integrations/serverless-framework/ /aws/connecting/infrastructure-as-code/serverless-framework/ 301 @@ -168,7 +164,7 @@ /user-guide/ci/bitbucket/ /aws/ci-pipelines/bitbucket/ 301 /contributing/ https://github.com/localstack/localstack/blob/main/docs/CONTRIBUTING.md 301 /user-guide/aws/scheduler/ /aws/services/scheduler/ 301 -/user-guide/integrations/quarkus/ /aws/integrations/app-frameworks/quarkus/ 301 +/user-guide/integrations/quarkus/ /aws/customization/integrations/app-frameworks/quarkus/ 301 /user-guide/aws/servicediscovery/ /aws/services/servicediscovery/ 301 /academy/localstack-101/ https://www.youtube.com/playlist?list=PLTew28KOwGxPqbkFiW518eeIfiV495bm0&si=rKhzdxOJsfO_pgyk 301 /user-guide/aws/xray/ /aws/services/xray/ 301 @@ -178,18 +174,17 @@ /user-guide/aws/apigateway/ /aws/services/apigateway/ 301 /user-guide/integrations/cloud-custodian/ /aws/connecting/infrastructure-as-code/cloud-custodian/ 301 /references/coverage/coverage_lambda/ /aws/services/lambda/ 301 -/user-guide/integrations/sdks/java/ /aws/connecting/aws-sdks/net/java/ 301 +/user-guide/integrations/sdks/java/ /aws/connecting/aws-sdks/java/ 301 /references/coverage/coverage_logs/ /aws/services/logs/ 301 -/references/coverage/coverage_mediastore/ /aws/services/mediastore/ 301 /user-guide/integrations/kafka/ /aws/customization/integrations/app-frameworks/selfmanaged-kafka-cluster/ 301 -/user-guide/chaos-engineering/fault-injection-service/ /aws/developer-tools/chaos-engineering/fault-injection-service/ 301 +/user-guide/chaos-engineering/fault-injection-service/ /aws/developer-tools/chaos-engineering/aws-fault-injection/ 301 /references/logging/ /aws/customization/logging/ 301 /tutorials/java-notification-app/ /aws/tutorials/java-notification-app/ 301 /applications/serverless-transcription-application-using-transcribe-s3-lambda-sqs-and-ses/ https://github.com/localstack-samples/sample-serverless-transcribe 301 /user-guide/aws/route53resolver/ /aws/services/route53resolver/ 301 /references/coverage/coverage_wafv2/ /aws/services/waf/ 301 -/user-guide/integrations/sdks/cpp/ /aws/connecting/aws-sdks/net/cpp/ 301 -/user-guide/integrations/testcontainers/ /aws/integrations/testing/testcontainers/ 301 +/user-guide/integrations/sdks/cpp/ /aws/connecting/aws-sdks/cpp/ 301 +/user-guide/integrations/testcontainers/ /aws/customization/integrations/testing/testcontainers/ 301 /references/internal-endpoints/ /aws/customization/networking/internal-endpoints/ 301 /tutorials/lambda-ecr-container-images/ /aws/tutorials/lambda-ecr-container-images/ 301 /user-guide/aws/fis/ /aws/services/fis/ 301 @@ -199,9 +194,9 @@ /user-guide/web-application/resource-browser/ /aws/connecting/console/resource-browser/ 301 /applications/loan-broker-application-with-aws-step-functions-dynamodb-lambda-sqs-and-sns/ https://github.com/localstack-samples/sample-loan-broker-stepfunctions-lambda 301 /references/coverage/coverage_resource-groups/ /aws/services/resource-groups/ 301 -/user-guide/state-management/support/ /aws/developer-tools/snapshots/persistence-coverage/ 301 +/user-guide/state-management/support/ /aws/developer-tools/snapshots/service-coverage/ 301 /references/coverage/coverage_redshift/ /aws/services/redshift/ 301 -/user-guide/integrations/lambdatest-hyperexecute/ /aws/integrations/testing/lambdatest-hyperexecute/ 301 +/user-guide/integrations/lambdatest-hyperexecute/ /aws/customization/integrations/testing/lambdatest-hyperexecute/ 301 /applications/ /aws/sample-apps/ 301 /user-guide/web-application/users-and-licenses/ /aws/organizations-admin/managing-users-licenses/ 301 /user-guide/tools/localstack-sdk/ /aws/customization/integrations/localstack-sdks/ 301 @@ -242,12 +237,11 @@ /user-guide/aws/cloudwatch/ /aws/services/cloudwatch/ 301 /user-guide/aws/elasticbeanstalk/ /aws/services/elasticbeanstalk/ 301 /references/coverage/coverage_mediaconvert/ /aws/services/mediaconvert/ 301 -/user-guide/state-management/launchpad/ /aws/developer-tools/snapshots/launchpad/ 301 +/user-guide/state-management/launchpad/ /aws/developer-tools/snapshots/ 301 /user-guide/ci/codebuild/ /aws/ci-pipelines/codebuild/ 301 /user-guide/aws/iot-data/ /aws/services/iot-data/ 301 /references/coverage/coverage_textract/ /aws/services/textract/ 301 /references/coverage/coverage_codebuild/ /aws/services/codebuild/ 301 -/user-guide/aws/elastictranscoder/ /aws/services/elastictranscoder/ 301 /references/coverage/coverage_glacier/ /aws/services/glacier/ 301 /user-guide/tools/ /aws/developer-tools/ 301 /user-guide/aws/timestream/ /aws/services/timestream-query/ 301 @@ -260,7 +254,7 @@ /user-guide/aws/kinesis/ /aws/services/kinesis/ 301 /references/coverage/coverage_bedrock-runtime/ /aws/services/bedrock/ 301 /references/coverage/coverage_iot-data/ /aws/services/iot-data/ 301 -/user-guide/cloud-sandbox/ephemeral-instance/ /aws/developer-tools/cloud-sandbox/ephemeral-instance/ 301 +/user-guide/cloud-sandbox/ephemeral-instance/ /aws/developer-tools/cloud-sandbox/ephemeral-instances/ 301 /references/coverage/coverage_timestream-write/ /aws/services/timestream-query/ 301 /user-guide/aws/pinpoint/ /aws/services/pinpoint/ 301 /tutorials/cloud-pods-collaborative-debugging/ /aws/tutorials/cloud-pods-collaborative-debugging/ 301 @@ -283,10 +277,10 @@ /references/coverage/coverage_ecr/ /aws/services/ecr/ 301 /academy/localstack-deployment/ https://www.youtube.com/playlist?list=PLTew28KOwGxPdtdW00WNXZLZnstvRQyTF&si=R-Ed-JQKOxXP473O 301 /references/coverage/coverage_application-autoscaling/ /aws/services/application-autoscaling/ 301 -/user-guide/lambda-tools/debugging/ /aws/developer-tools/lambda-tools/debugging/ 301 +/user-guide/lambda-tools/debugging/ /aws/developer-tools/lambda-tools/remote-debugging/ 301 /references/coverage/coverage_codestar-connections/ /aws/services/codeconnections/ 301 /user-guide/integrations/rancher-desktop/ /aws/customization/other-installations/rancher-desktop/ 301 -/user-guide/integrations/sdks/ruby/ /aws/connecting/aws-sdks/net/ruby/ 301 +/user-guide/integrations/sdks/ruby/ /aws/connecting/aws-sdks/ruby/ 301 /user-guide/aws/mwaa/ /aws/services/mwaa/ 301 /academy/localstack-deployment/deploy-app-ls/ https://www.youtube.com/watch?list=PLTew28KOwGxPdtdW00WNXZLZnstvRQyTF&v=qIB79b-iw2U&feature=youtu.be 301 /user-guide/aws/organizations/ /aws/services/organizations/ 301 @@ -295,19 +289,18 @@ /references/configuration/ /aws/customization/configuration-options/ 301 /user-guide/chaos-engineering/chaos-api/ /aws/developer-tools/chaos-engineering/chaos-api/ 301 /user-guide/aws/glacier/ /aws/services/glacier/ 301 -/references/coverage/coverage_qldb-session/ /aws/services/qldb/ 301 /user-guide/integrations/pulumi/ /aws/connecting/infrastructure-as-code/pulumi/ 301 /user-guide/aws/cloudtrail/ /aws/services/cloudtrail/ 301 /references/coverage/coverage_s3/ /aws/services/s3/ 301 /user-guide/aws/emr/ /aws/services/emr/ 301 /user-guide/tools/dns-server/ /aws/customization/networking/dns-server/ 301 -/user-guide/chaos-engineering/chaos-application-dashboard/ /aws/developer-tools/chaos-engineering/chaos-application-dashboard/ 301 +/user-guide/chaos-engineering/chaos-application-dashboard/ /aws/developer-tools/chaos-engineering/chaos-engineering-dashboard/ 301 /references/coverage/coverage_route53/ /aws/services/route53/ 301 /references/coverage/coverage_dynamodbstreams/ /aws/services/dynamodbstreams/ 301 /references/coverage/coverage_dynamodb/ /aws/services/dynamodb/ 301 /user-guide/aws/ec2/ /aws/services/ec2/ 301 /user-guide/cloud-sandbox/application-previews/ /aws/developer-tools/cloud-sandbox/app-preview/ 301 -/user-guide/integrations/spring-cloud-function/ /aws/integrations/app-frameworks/spring-cloud-function/ 301 +/user-guide/integrations/spring-cloud-function/ /aws/customization/integrations/app-frameworks/spring-cloud-function/ 301 /references/multi-account-setups/ /aws/customization/advanced/multi-account-setups/ 301 /user-guide/aws/elementalmediaconvert/ /aws/services/mediaconvert/ 301 /references/coverage/coverage_shield/ /aws/services/shield/ 301 @@ -322,7 +315,7 @@ /references/coverage/coverage_appconfig/ /aws/services/appconfig/ 301 /references/coverage/coverage_iot/ /aws/services/iot/ 301 /getting-started/installation/ /aws/getting-started/installation/ 301 -/user-guide/integrations/architect/ /aws/integrations/app-frameworks/architect/ 301 +/user-guide/integrations/architect/ /aws/customization/integrations/app-frameworks/architect/ 301 /user-guide/integrations/gitpod/ /aws/customization/other-installations/ 301 /user-guide/aws/managedblockchain/ /aws/services/managedblockchain/ 301 /applications/query-data-in-s3-bucket-with-amazon-athena-glue-catalog-cloudformation/ https://github.com/localstack-samples/sample-query-data-s3-athena-glue 301 @@ -337,7 +330,7 @@ /user-guide/aws/iot/ /aws/services/iot/ 301 /user-guide/aws/backup/ /aws/services/backup/ 301 /references/coverage/coverage_organizations/ /aws/services/organizations/ 301 -/user-guide/aws/kinesisanalytics/ /aws/services/kinesisanalytics/ 301 +/user-guide/aws/kinesisanalytics/ /aws/services/kinesisanalyticsv2/ 301 /user-guide/localstack-enterprise/single-sign-on/ /aws/organizations-admin/sso/ 301 /user-guide/aws/redshift/ /aws/services/redshift/ 301 /references/coverage/coverage_verifiedpermissions/ /aws/services/verifiedpermissions/ 301 @@ -345,7 +338,7 @@ /applications/full-stack-application-with-aws-lambda-dynamodb-s3-for-shipment-validation/ https://github.com/localstack-samples/sample-shipment-list-demo-lambda-dynamodb-s3 301 /user-guide/integrations/chalice/ /aws/connecting/infrastructure-as-code/aws-chalice/ 301 /user-guide/security-testing/iam-policy-stream/ /aws/developer-tools/security-testing/iam-policy-stream/ 301 -/user-guide/security-testing/iam-enforcement/ /aws/developer-tools/security-testing/iam-enforcement/ 301 +/user-guide/security-testing/iam-enforcement/ /aws/developer-tools/security-testing/iam-policy-enforcement/ 301 /references/coverage/coverage_route53resolver/ /aws/services/route53resolver/ 301 /references/coverage/coverage_config/ /aws/services/config/ 301 /references/coverage/coverage_account/ /aws/services/account/ 301 @@ -363,7 +356,7 @@ /user-guide/aws/elasticache/ /aws/services/elasticache/ 301 /tutorials/using-terraform-with-testcontainers-and-localstack/ /aws/tutorials/using-terraform-with-testcontainers-and-localstack/ 301 /references/coverage/coverage_cloudfront/ /aws/services/cloudfront/ 301 -/user-guide/tools/localstack-sdk/java/ /aws/user-guide/tools/localstack-sdk/java/ 301 +/user-guide/tools/localstack-sdk/java/ /aws/customization/integrations/localstack-sdks/java-sdk/ 301 /references/network-troubleshooting/readme/ /aws/customization/networking/ 301 /user-guide/aws/codecommit/ /aws/services/codecommit/ 301 /references/coverage/coverage_swf/ /aws/services/swf/ 301 @@ -372,29 +365,28 @@ /references/init-hooks/ /aws/customization/advanced/initialization-hooks/ 301 /references/coverage/coverage_support/ /aws/services/support/ 301 /user-guide/ /aws/ 301 -/user-guide/aws/qldb/ /aws/services/qldb/ 301 /tutorials/simulating-outages/ /aws/tutorials/simulating-outages/ 301 /user-guide/aws/acm/ /aws/services/acm/ 301 -/user-guide/integrations/sdks/php/ /aws/connecting/aws-sdks/net/php/ 301 +/user-guide/integrations/sdks/php/ /aws/connecting/aws-sdks/php/ 301 /references/coverage/coverage_sns/ /aws/services/sns/ 301 -/getting-started/help-and-support/ /aws/getting-started/help-support/ 301 +/getting-started/help-and-support/ /aws/help-support/ 301 /user-guide/aws/amplify/ /aws/services/amplify/ 301 /references/coverage/coverage_lakeformation/ /aws/services/lakeformation/ 301 -/user-guide/integrations/sdks/dotnet/ /aws/connecting/aws-sdks/net/dotnet/ 301 +/user-guide/integrations/sdks/dotnet/ /aws/connecting/aws-sdks/dotnet/ 301 /academy/ https://www.youtube.com/playlist?list=PLTew28KOwGxPqbkFiW518eeIfiV495bm0 301 /references/coverage/coverage_cloudwatch/ /aws/services/cloudwatch/ 301 /user-guide/aws/ecr/ /aws/services/ecr/ 301 /user-guide/aws/stepfunctions/ /aws/services/stepfunctions/ 301 /references/coverage/coverage_elasticache/ /aws/services/elasticache/ 301 /applications/mnist-handwritten-digit-recognition-model-running-on-a-local-sagemaker-endpoint/ https://github.com/localstack-samples/sample-mnist-digit-recognition-sagemaker 301 -/user-guide/state-management/pods-cli/ /aws/developer-tools/snapshots/cli-commands/ 301 +/user-guide/state-management/pods-cli/ /aws/developer-tools/running-localstack/lstk/#snapshot 301 /user-guide/aws/dynamodbstreams/ /aws/services/dynamodbstreams/ 301 /references/api-key/ /aws/getting-started/auth-token/#how-do-i-activate-older-versions-of-localstack-before-v30/ 301 /references/coverage/coverage_eks/ /aws/services/eks/ 301 /references/coverage/coverage_cognito-idp/ /aws/services/cognito-idp/ 301 /user-guide/web-application/workspace/ /aws/organizations-admin/workspaces/ 301 /references/coverage/coverage_cloudcontrol/ /aws/services/cloudcontrol/ 301 -/tutorials/replicate-aws-resources-localstack-extension/ /aws/tutorials/replicate-aws-resources-localstack-extension/ 301 +/tutorials/replicate-aws-resources-localstack-extension/ /aws/developer-tools/aws-replicator/ 301 /user-guide/tools/localstack-sdk/python/ /aws/customization/integrations/localstack-sdks/python-sdk/ 301 /user-guide/lambda-tools/hot-reloading/ /aws/developer-tools/lambda-tools/hot-reloading/ 301 /getting-started/quickstart/ /aws/getting-started/quickstart/ 301 @@ -437,7 +429,7 @@ /applications/appsync-graphql-apis-for-dynamodb-and-rds-aurora-postgresql https://github.com/localstack-samples/sample-appsync-graphql-api 301 /user-guide/aws/cloudfront /aws/services/cloudfront/ 301 /applications/note-taking-application-using-aws-sdk-for-javascript https://github.com/localstack-samples/sample-notes-app-dynamodb-lambda-apigateway 301 -/user-guide/state-management/export-import-state /aws/developer-tools/snapshots/export-import-state/ 301 +/user-guide/state-management/export-import-state /aws/developer-tools/snapshots/saving-snapshots-locally/ 301 /references/coverage/coverage_s3control /aws/services/s3/ 301 /references/custom-tls-certificates /aws/developer-tools/security-testing/custom-tls-certificates/ 301 /references/coverage/coverage_codecommit /aws/services/codecommit/ 301 @@ -445,13 +437,13 @@ /user-guide/tools/testing-utils /aws/customization/integrations/localstack-sdks/testing-utils/ 301 /user-guide/aws/codedeploy /aws/services/codedeploy/ 301 /references/coverage/coverage_serverlessrepo /aws/services/serverlessrepo/ 301 -/user-guide/aws/resource_groups /aws/services/resource_groups/ 301 +/user-guide/aws/resource_groups /aws/services/resource-groups/ 301 /references/coverage/coverage_glue /aws/services/glue/ 301 /user-guide/aws/ssm /aws/services/ssm/ 301 /references/coverage/coverage_sts /aws/services/sts/ 301 /academy/localstack-101/course-overview https://www.youtube.com/watch?list=PLTew28KOwGxPqbkFiW518eeIfiV495bm0&v=VLL-BI1AWcc&feature=youtu.be 301 /user-guide/aws/iotwireless /aws/services/iotwireless/ 301 -/user-guide/integrations/sdks/python /aws/connecting/aws-sdks/net/python/ 301 +/user-guide/integrations/sdks/python /aws/connecting/aws-sdks/python-boto3/ 301 /user-guide/integrations/crossplane /aws/connecting/infrastructure-as-code/crossplane/ 301 /references/coverage/coverage_elbv2 /aws/services/elb/ 301 /user-guide/integrations/openshift /aws/customization/kubernetes/openshift/ 301 @@ -482,7 +474,6 @@ /references/coverage/coverage_kms /aws/services/kms/ 301 /applications/step-up-authentication-using-amazon-cognito https://github.com/localstack-samples/sample-cdk-cognito-dynamodb-api-gateway 301 /references/coverage/coverage_athena /aws/services/athena/ 301 -/user-guide/aws/mediastore /aws/services/mediastore/ 301 /references/coverage/coverage_fis /aws/services/fis/ 301 /user-guide/aws/logs /aws/services/logs/ 301 /academy/localstack-deployment/infra-cloudformation https://www.youtube.com/watch?list=PLTew28KOwGxPdtdW00WNXZLZnstvRQyTF&v=K0OgQ5eq588&feature=youtu.be 301 @@ -493,7 +484,6 @@ /references/credentials /aws/connecting/credentials/ 301 /references/coverage/coverage_elasticbeanstalk /aws/services/elasticbeanstalk/ 301 /user-guide/web-application/instance-management /aws/connecting/console/instance-management/ 301 -/references/coverage/coverage_qldb /aws/services/qldb/ 301 /academy/localstack-deployment/iam-policy-stream https://www.youtube.com/watch?list=PLTew28KOwGxPdtdW00WNXZLZnstvRQyTF&v=TOBLG2Z6xAM&feature=youtu.be 301 /references/cross-account-access /aws/customization/advanced/cross-account-access/ 301 /tutorials/reproducible-machine-learning-cloud-pods /aws/tutorials/reproducible-machine-learning-cloud-pods/ 301 @@ -527,12 +517,11 @@ /user-guide/localstack-enterprise/single-sign-on/azure-ad /aws/organizations-admin/sso/azure-ad/ 301 /user-guide/tools/localstack-desktop /aws/developer-tools/running-localstack/localstack-desktop/ 301 /references/coverage/coverage_es /aws/services/es/ 301 -/user-guide/integrations/sdks/javascript /aws/connecting/aws-sdks/net/javascript/ 301 +/user-guide/integrations/sdks/javascript /aws/connecting/aws-sdks/javascript/ 301 /references/coverage/coverage_iam /aws/services/iam/ 301 -/user-guide/tools/localsurf /aws/customization/networking/localsurf/ 301 +/user-guide/tools/localsurf /aws/customization/networking/ 301 /user-guide/extensions/extensions-library /aws/customization/integrations/extensions/extensions-library/ 301 /tutorials/ecs-ecr-container-app /aws/tutorials/ecs-ecr-container-app/ 301 -/references/coverage/coverage_elastictranscoder /aws/services/elastictranscoder/ 301 /user-guide/aws/feature-coverage /aws/services/ 301 /user-guide/aws/lambda /aws/services/lambda/ 301 /references/iam-coverage /aws/developer-tools/security-testing/iam-coverage/ 301 @@ -544,12 +533,11 @@ /user-guide/aws/s3 /aws/services/s3/ 301 /user-guide/lambda-tools/vscode-extension /aws/connecting/ides/vscode-extension/ 301 /user-guide/chaos-engineering /aws/developer-tools/chaos-engineering/ 301 -/persistence/supported /aws/developer-tools/snapshots/persistence/ 301 +/persistence/supported /aws/developer-tools/snapshots/service-coverage/ 301 /user-guide/aws/ce /aws/services/ce/ 301 /user-guide/aws/kinesisanalyticsv2 /aws/services/kinesisanalyticsv2/ 301 /user-guide/state-management/cloud-pods /aws/developer-tools/snapshots/cloud-pods/ 301 /references/coverage/coverage_transcribe /aws/services/transcribe/ 301 -/references/coverage/coverage_mediastore-data /aws/services/mediastore/ 301 /user-guide/aws/route53 /aws/services/route53/ 301 /user-guide/aws/config /aws/services/config/ 301 /references/coverage/coverage_identitystore /aws/services/identitystore/ 301 @@ -565,7 +553,7 @@ /developer-hub /aws/sample-apps/ 301 /references/coverage/coverage_firehose /aws/services/firehose/ 301 /user-guide/aws/verifiedpermissions /aws/services/verifiedpermissions/ 301 -/references/coverage/coverage_kinesisanalytics /aws/services/kinesisanalytics/ 301 +/references/coverage/coverage_kinesisanalytics /aws/services/kinesisanalyticsv2/ 301 /user-guide/aws/sns /aws/services/sns/ 301 /user-guide/tools/aws-replicator /aws/developer-tools/aws-replicator/ 301 /user-guide/integrations/serverless-framework /aws/connecting/infrastructure-as-code/serverless-framework/ 301 @@ -575,7 +563,7 @@ /user-guide/ci/bitbucket /aws/ci-pipelines/bitbucket/ 301 /contributing https://github.com/localstack/localstack/blob/master/docs/CONTRIBUTING.md 301 /user-guide/aws/scheduler /aws/services/scheduler/ 301 -/user-guide/integrations/quarkus /aws/integrations/app-frameworks/quarkus/ 301 +/user-guide/integrations/quarkus /aws/customization/integrations/app-frameworks/quarkus/ 301 /user-guide/aws/servicediscovery /aws/services/servicediscovery/ 301 /academy/localstack-101 https://www.youtube.com/playlist?list=PLTew28KOwGxPqbkFiW518eeIfiV495bm0&si=rKhzdxOJsfO_pgyk 301 /user-guide/aws/xray /aws/services/xray/ 301 @@ -585,18 +573,17 @@ /user-guide/aws/apigateway /aws/services/apigateway/ 301 /user-guide/integrations/cloud-custodian /aws/connecting/infrastructure-as-code/cloud-custodian/ 301 /references/coverage/coverage_lambda /aws/services/lambda/ 301 -/user-guide/integrations/sdks/java /aws/connecting/aws-sdks/net/java/ 301 +/user-guide/integrations/sdks/java /aws/connecting/aws-sdks/java/ 301 /references/coverage/coverage_logs /aws/services/logs/ 301 -/references/coverage/coverage_mediastore /aws/services/mediastore/ 301 /user-guide/integrations/kafka /aws/customization/integrations/app-frameworks/selfmanaged-kafka-cluster/ 301 -/user-guide/chaos-engineering/fault-injection-service /aws/developer-tools/chaos-engineering/fault-injection-service/ 301 +/user-guide/chaos-engineering/fault-injection-service /aws/developer-tools/chaos-engineering/aws-fault-injection/ 301 /references/logging /aws/customization/logging/ 301 /tutorials/java-notification-app /aws/tutorials/java-notification-app/ 301 /applications/serverless-transcription-application-using-transcribe-s3-lambda-sqs-and-ses https://github.com/localstack-samples/sample-serverless-transcribe 301 /user-guide/aws/route53resolver /aws/services/route53resolver/ 301 /references/coverage/coverage_wafv2 /aws/services/waf/ 301 -/user-guide/integrations/sdks/cpp /aws/connecting/aws-sdks/net/cpp/ 301 -/user-guide/integrations/testcontainers /aws/integrations/testing/testcontainers/ 301 +/user-guide/integrations/sdks/cpp /aws/connecting/aws-sdks/cpp/ 301 +/user-guide/integrations/testcontainers /aws/customization/integrations/testing/testcontainers/ 301 /references/internal-endpoints /aws/customization/networking/internal-endpoints/ 301 /tutorials/lambda-ecr-container-images /aws/tutorials/lambda-ecr-container-images/ 301 /user-guide/aws/fis /aws/services/fis/ 301 @@ -606,9 +593,9 @@ /user-guide/web-application/resource-browser /aws/connecting/console/resource-browser/ 301 /applications/loan-broker-application-with-aws-step-functions-dynamodb-lambda-sqs-and-sns https://github.com/localstack-samples/sample-loan-broker-stepfunctions-lambda 301 /references/coverage/coverage_resource-groups /aws/services/resource-groups/ 301 -/user-guide/state-management/support /aws/developer-tools/snapshots/persistence-coverage/ 301 +/user-guide/state-management/support /aws/developer-tools/snapshots/service-coverage/ 301 /references/coverage/coverage_redshift /aws/services/redshift/ 301 -/user-guide/integrations/lambdatest-hyperexecute /aws/integrations/testing/lambdatest-hyperexecute/ 301 +/user-guide/integrations/lambdatest-hyperexecute /aws/customization/integrations/testing/lambdatest-hyperexecute/ 301 /applications /aws/sample-apps/ 301 /user-guide/web-application/users-and-licenses /aws/organizations-admin/managing-users-licenses/ 301 /user-guide/tools/localstack-sdk /aws/customization/integrations/localstack-sdks/ 301 @@ -649,12 +636,11 @@ /user-guide/aws/cloudwatch /aws/services/cloudwatch/ 301 /user-guide/aws/elasticbeanstalk /aws/services/elasticbeanstalk/ 301 /references/coverage/coverage_mediaconvert /aws/services/mediaconvert/ 301 -/user-guide/state-management/launchpad /aws/developer-tools/snapshots/launchpad/ 301 +/user-guide/state-management/launchpad /aws/developer-tools/snapshots/ 301 /user-guide/ci/codebuild /aws/ci-pipelines/codebuild/ 301 /user-guide/aws/iot-data /aws/services/iot-data/ 301 /references/coverage/coverage_textract /aws/services/textract/ 301 /references/coverage/coverage_codebuild /aws/services/codebuild/ 301 -/user-guide/aws/elastictranscoder /aws/services/elastictranscoder/ 301 /references/coverage/coverage_glacier /aws/services/glacier/ 301 /user-guide/tools /aws/developer-tools/ 301 /user-guide/aws/timestream /aws/services/timestream-query/ 301 @@ -667,7 +653,7 @@ /user-guide/aws/kinesis /aws/services/kinesis/ 301 /references/coverage/coverage_bedrock-runtime /aws/services/bedrock/ 301 /references/coverage/coverage_iot-data /aws/services/iot-data/ 301 -/user-guide/cloud-sandbox/ephemeral-instance /aws/developer-tools/cloud-sandbox/ephemeral-instance/ 301 +/user-guide/cloud-sandbox/ephemeral-instance /aws/developer-tools/cloud-sandbox/ephemeral-instances/ 301 /references/coverage/coverage_timestream-write /aws/services/timestream-query/ 301 /user-guide/aws/pinpoint /aws/services/pinpoint/ 301 /tutorials/cloud-pods-collaborative-debugging /aws/tutorials/cloud-pods-collaborative-debugging/ 301 @@ -690,10 +676,10 @@ /references/coverage/coverage_ecr /aws/services/ecr/ 301 /academy/localstack-deployment https://www.youtube.com/playlist?list=PLTew28KOwGxPdtdW00WNXZLZnstvRQyTF&si=R-Ed-JQKOxXP473O 301 /references/coverage/coverage_application-autoscaling /aws/services/application-autoscaling/ 301 -/user-guide/lambda-tools/debugging /aws/developer-tools/lambda-tools/debugging/ 301 +/user-guide/lambda-tools/debugging /aws/developer-tools/lambda-tools/remote-debugging/ 301 /references/coverage/coverage_codestar-connections /aws/services/codeconnections/ 301 /user-guide/integrations/rancher-desktop /aws/customization/other-installations/rancher-desktop/ 301 -/user-guide/integrations/sdks/ruby /aws/connecting/aws-sdks/net/ruby/ 301 +/user-guide/integrations/sdks/ruby /aws/connecting/aws-sdks/ruby/ 301 /user-guide/aws/mwaa /aws/services/mwaa/ 301 /academy/localstack-deployment/deploy-app-ls https://www.youtube.com/watch?list=PLTew28KOwGxPdtdW00WNXZLZnstvRQyTF&v=qIB79b-iw2U&feature=youtu.be 301 /user-guide/aws/organizations /aws/services/organizations/ 301 @@ -702,19 +688,18 @@ /references/configuration /aws/customization/configuration-options/ 301 /user-guide/chaos-engineering/chaos-api /aws/developer-tools/chaos-engineering/chaos-api/ 301 /user-guide/aws/glacier /aws/services/glacier/ 301 -/references/coverage/coverage_qldb-session /aws/services/qldb/ 301 /user-guide/integrations/pulumi /aws/connecting/infrastructure-as-code/pulumi/ 301 /user-guide/aws/cloudtrail /aws/services/cloudtrail/ 301 /references/coverage/coverage_s3 /aws/services/s3/ 301 /user-guide/aws/emr /aws/services/emr/ 301 /user-guide/tools/dns-server /aws/customization/networking/dns-server/ 301 -/user-guide/chaos-engineering/chaos-application-dashboard /aws/developer-tools/chaos-engineering/chaos-application-dashboard/ 301 +/user-guide/chaos-engineering/chaos-application-dashboard /aws/developer-tools/chaos-engineering/chaos-engineering-dashboard/ 301 /references/coverage/coverage_route53 /aws/services/route53/ 301 /references/coverage/coverage_dynamodbstreams /aws/services/dynamodbstreams/ 301 /references/coverage/coverage_dynamodb /aws/services/dynamodb/ 301 /user-guide/aws/ec2 /aws/services/ec2/ 301 /user-guide/cloud-sandbox/application-previews /aws/developer-tools/cloud-sandbox/app-preview/ 301 -/user-guide/integrations/spring-cloud-function /aws/integrations/app-frameworks/spring-cloud-function/ 301 +/user-guide/integrations/spring-cloud-function /aws/customization/integrations/app-frameworks/spring-cloud-function/ 301 /references/multi-account-setups /aws/customization/advanced/multi-account-setups/ 301 /user-guide/aws/elementalmediaconvert /aws/services/mediaconvert/ 301 /references/coverage/coverage_shield /aws/services/shield/ 301 @@ -729,7 +714,7 @@ /references/coverage/coverage_appconfig /aws/services/appconfig/ 301 /references/coverage/coverage_iot /aws/services/iot/ 301 /getting-started/installation /aws/getting-started/installation/ 301 -/user-guide/integrations/architect /aws/integrations/app-frameworks/architect/ 301 +/user-guide/integrations/architect /aws/customization/integrations/app-frameworks/architect/ 301 /user-guide/integrations/gitpod /aws/customization/other-installations/ 301 /user-guide/aws/managedblockchain /aws/services/managedblockchain/ 301 /applications/query-data-in-s3-bucket-with-amazon-athena-glue-catalog-cloudformation https://github.com/localstack-samples/sample-query-data-s3-athena-glue 301 @@ -744,7 +729,7 @@ /user-guide/aws/iot /aws/services/iot/ 301 /user-guide/aws/backup /aws/services/backup/ 301 /references/coverage/coverage_organizations /aws/services/organizations/ 301 -/user-guide/aws/kinesisanalytics /aws/services/kinesisanalytics/ 301 +/user-guide/aws/kinesisanalytics /aws/services/kinesisanalyticsv2/ 301 /user-guide/localstack-enterprise/single-sign-on /aws/organizations-admin/sso/ 301 /user-guide/aws/redshift /aws/services/redshift/ 301 /references/coverage/coverage_verifiedpermissions /aws/services/verifiedpermissions/ 301 @@ -752,7 +737,7 @@ /applications/full-stack-application-with-aws-lambda-dynamodb-s3-for-shipment-validation https://github.com/localstack-samples/sample-shipment-list-demo-lambda-dynamodb-s3 301 /user-guide/integrations/chalice /aws/connecting/infrastructure-as-code/aws-chalice/ 301 /user-guide/security-testing/iam-policy-stream /aws/developer-tools/security-testing/iam-policy-stream/ 301 -/user-guide/security-testing/iam-enforcement /aws/developer-tools/security-testing/iam-enforcement/ 301 +/user-guide/security-testing/iam-enforcement /aws/developer-tools/security-testing/iam-policy-enforcement/ 301 /references/coverage/coverage_route53resolver /aws/services/route53resolver/ 301 /references/coverage/coverage_config /aws/services/config/ 301 /references/coverage/coverage_account /aws/services/account/ 301 @@ -770,7 +755,7 @@ /user-guide/aws/elasticache /aws/services/elasticache/ 301 /tutorials/using-terraform-with-testcontainers-and-localstack /aws/tutorials/using-terraform-with-testcontainers-and-localstack/ 301 /references/coverage/coverage_cloudfront /aws/services/cloudfront/ 301 -/user-guide/tools/localstack-sdk/java /aws/user-guide/tools/localstack-sdk/java/ 301 +/user-guide/tools/localstack-sdk/java /aws/customization/integrations/localstack-sdks/java-sdk/ 301 /references/network-troubleshooting/readme /aws/customization/networking/ 301 /user-guide/aws/codecommit /aws/services/codecommit/ 301 /references/coverage/coverage_swf /aws/services/swf/ 301 @@ -779,29 +764,28 @@ /references/init-hooks /aws/customization/advanced/initialization-hooks/ 301 /references/coverage/coverage_support /aws/services/support/ 301 /user-guide /aws/ 301 -/user-guide/aws/qldb /aws/services/qldb/ 301 /tutorials/simulating-outages /aws/tutorials/simulating-outages/ 301 /user-guide/aws/acm /aws/services/acm/ 301 -/user-guide/integrations/sdks/php /aws/connecting/aws-sdks/net/php/ 301 +/user-guide/integrations/sdks/php /aws/connecting/aws-sdks/php/ 301 /references/coverage/coverage_sns /aws/services/sns/ 301 -/getting-started/help-and-support /aws/getting-started/help-support/ 301 +/getting-started/help-and-support /aws/help-support/ 301 /user-guide/aws/amplify /aws/services/amplify/ 301 /references/coverage/coverage_lakeformation /aws/services/lakeformation/ 301 -/user-guide/integrations/sdks/dotnet /aws/connecting/aws-sdks/net/dotnet/ 301 +/user-guide/integrations/sdks/dotnet /aws/connecting/aws-sdks/dotnet/ 301 /academy https://www.youtube.com/playlist?list=PLTew28KOwGxPqbkFiW518eeIfiV495bm0 301 /references/coverage/coverage_cloudwatch /aws/services/cloudwatch/ 301 /user-guide/aws/ecr /aws/services/ecr/ 301 /user-guide/aws/stepfunctions /aws/services/stepfunctions/ 301 /references/coverage/coverage_elasticache /aws/services/elasticache/ 301 /applications/mnist-handwritten-digit-recognition-model-running-on-a-local-sagemaker-endpoint https://github.com/localstack-samples/sample-mnist-digit-recognition-sagemaker 301 -/user-guide/state-management/pods-cli /aws/developer-tools/snapshots/cli-commands/ 301 +/user-guide/state-management/pods-cli /aws/developer-tools/running-localstack/lstk/#snapshot 301 /user-guide/aws/dynamodbstreams /aws/services/dynamodbstreams/ 301 /references/api-key /aws/getting-started/auth-token/#how-do-i-activate-older-versions-of-localstack-before-v30/ 301 /references/coverage/coverage_eks /aws/services/eks/ 301 /references/coverage/coverage_cognito-idp /aws/services/cognito-idp/ 301 /user-guide/web-application/workspace /aws/organizations-admin/workspaces/ 301 /references/coverage/coverage_cloudcontrol /aws/services/cloudcontrol/ 301 -/tutorials/replicate-aws-resources-localstack-extension /aws/tutorials/replicate-aws-resources-localstack-extension/ 301 +/tutorials/replicate-aws-resources-localstack-extension /aws/developer-tools/aws-replicator/ 301 /user-guide/tools/localstack-sdk/python /aws/customization/integrations/localstack-sdks/python-sdk/ 301 /user-guide/lambda-tools/hot-reloading /aws/developer-tools/lambda-tools/hot-reloading/ 301 /getting-started/quickstart /aws/getting-started/quickstart/ 301 @@ -839,8 +823,8 @@ /aws/integrations/aws-sdks/java /aws/connecting/aws-sdks/java/ 301 /aws/integrations/aws-sdks/javascript/ /aws/connecting/aws-sdks/javascript/ 301 /aws/integrations/aws-sdks/javascript /aws/connecting/aws-sdks/javascript/ 301 -/aws/integrations/aws-sdks/net/ /aws/connecting/aws-sdks/net/ 301 -/aws/integrations/aws-sdks/net /aws/connecting/aws-sdks/net/ 301 +/aws/integrations/aws-sdks/net/ /aws/connecting/aws-sdks/ 301 +/aws/integrations/aws-sdks/net /aws/connecting/aws-sdks/ 301 /aws/integrations/aws-sdks/php/ /aws/connecting/aws-sdks/php/ 301 /aws/integrations/aws-sdks/php /aws/connecting/aws-sdks/php/ 301 /aws/integrations/aws-sdks/python-boto3/ /aws/connecting/aws-sdks/python-boto3/ 301 @@ -875,13 +859,19 @@ /aws/integrations/aws-native-tools /aws/connecting/ 301 /aws/integrations/infrastructure-as-code/ /aws/connecting/infrastructure-as-code/ 301 /aws/integrations/infrastructure-as-code /aws/connecting/infrastructure-as-code/ 301 -/aws/capabilities/state-management/cli-commands /aws/developer-tools/snapshots/cli-commands/ 301 -/aws/capabilities/state-management/cli-commands/ /aws/developer-tools/snapshots/cli-commands/ 301 -/aws/capabilities/state-management/export-import-state /aws/developer-tools/snapshots/export-import-state/ 301 -/aws/capabilities/state-management/export-import-state/ /aws/developer-tools/snapshots/export-import-state/ 301 +/aws/capabilities/state-management/cli-commands /aws/developer-tools/running-localstack/lstk/#snapshot 301 +/aws/capabilities/state-management/cli-commands/ /aws/developer-tools/running-localstack/lstk/#snapshot 301 +/aws/capabilities/state-management/export-import-state /aws/developer-tools/snapshots/saving-snapshots-locally/ 301 +/aws/capabilities/state-management/export-import-state/ /aws/developer-tools/snapshots/saving-snapshots-locally/ 301 /aws/capabilities/state-management/ /aws/developer-tools/snapshots/ 301 -/aws/capabilities/state-management/launchpad /aws/developer-tools/snapshots/launchpad/ 301 -/aws/capabilities/state-management/launchpad/ /aws/developer-tools/snapshots/launchpad/ 301 +/aws/developer-tools/snapshots/export-import-state /aws/developer-tools/snapshots/saving-snapshots-locally/ 301 +/aws/developer-tools/snapshots/export-import-state/ /aws/developer-tools/snapshots/saving-snapshots-locally/ 301 +/aws/developer-tools/snapshots/cli-commands /aws/developer-tools/running-localstack/lstk/#snapshot 301 +/aws/developer-tools/snapshots/cli-commands/ /aws/developer-tools/running-localstack/lstk/#snapshot 301 +/aws/developer-tools/snapshots/launchpad /aws/developer-tools/snapshots/ 301 +/aws/developer-tools/snapshots/launchpad/ /aws/developer-tools/snapshots/ 301 +/aws/capabilities/state-management/launchpad /aws/developer-tools/snapshots/ 301 +/aws/capabilities/state-management/launchpad/ /aws/developer-tools/snapshots/ 301 /aws/capabilities/state-management/cloud-pods /aws/developer-tools/snapshots/cloud-pods/ 301 /aws/capabilities/state-management/cloud-pods/ /aws/developer-tools/snapshots/cloud-pods/ 301 /aws/capabilities/state-management/persistence /aws/developer-tools/snapshots/persistence/ 301 @@ -944,8 +934,8 @@ /aws/tooling/testing-utils/ /aws/customization/integrations/localstack-sdks/testing-utils/ 301 /aws/tooling/localstack-docker-extension /aws/customization/other-installations/localstack-docker-extension/ 301 /aws/tooling/localstack-docker-extension/ /aws/customization/other-installations/localstack-docker-extension/ 301 -/aws/tooling/localsurf /aws/customization/networking/localsurf/ 301 -/aws/tooling/localsurf/ /aws/customization/networking/localsurf/ 301 +/aws/tooling/localsurf /aws/customization/networking/ 301 +/aws/tooling/localsurf/ /aws/customization/networking/ 301 /aws/tooling /aws/developer-tools/ 301 /aws/tooling/ /aws/developer-tools/ 301 @@ -987,8 +977,8 @@ /aws/capabilities/localstack-docker-extension/ /aws/customization/other-installations/localstack-docker-extension/ 301 /aws/capabilities/localstack-sdks /aws/customization/integrations/localstack-sdks/ 301 /aws/capabilities/localstack-sdks/ /aws/customization/integrations/localstack-sdks/ 301 -/aws/capabilities/localsurf /aws/customization/networking/localsurf/ 301 -/aws/capabilities/localsurf/ /aws/customization/networking/localsurf/ 301 +/aws/capabilities/localsurf /aws/customization/networking/ 301 +/aws/capabilities/localsurf/ /aws/customization/networking/ 301 /aws/capabilities/networking /aws/customization/networking/ 301 /aws/capabilities/networking/ /aws/customization/networking/ 301 /aws/capabilities/testing-utils /aws/customization/integrations/localstack-sdks/testing-utils/ 301 @@ -1008,7 +998,6 @@ /aws/capabilities/web-app/workspaces /aws/organizations-admin/workspaces/ 301 /aws/capabilities/web-app/workspaces/ /aws/organizations-admin/workspaces/ 301 -/aws/configuration/networking/* /aws/customization/networking/:splat 301 /aws/configuration/networking /aws/customization/networking/ 301 /aws/configuration/config/configuration /aws/customization/configuration-options/ 301 /aws/configuration/config/logging /aws/customization/logging/ 301 @@ -1025,12 +1014,10 @@ /aws/configuration/config/podman /aws/customization/other-installations/podman/ 301 /aws/configuration/config /aws/customization/ 301 /aws/configuration/dns-server /aws/customization/networking/dns-server/ 301 -/aws/configuration/localsurf /aws/customization/networking/localsurf/ 301 +/aws/configuration/localsurf /aws/customization/networking/ 301 /aws/configuration/testing-utils /aws/customization/integrations/localstack-sdks/testing-utils/ 301 /aws/configuration/localstack-docker-extension /aws/customization/other-installations/localstack-docker-extension/ 301 -/aws/configuration/localstack-sdks/* /aws/customization/integrations/localstack-sdks/:splat 301 /aws/configuration/localstack-sdks /aws/customization/integrations/localstack-sdks/ 301 -/aws/configuration/extensions/* /aws/customization/integrations/extensions/:splat 301 /aws/configuration/extensions /aws/customization/integrations/extensions/ 301 /aws/configuration/web-app/accounts /aws/organizations-admin/accounts/ 301 /aws/configuration/web-app/workspaces /aws/organizations-admin/workspaces/ 301 @@ -1073,7 +1060,7 @@ /aws/configuration/extensions/ /aws/customization/integrations/extensions/ 301 /aws/configuration/localstack-docker-extension/ /aws/customization/other-installations/localstack-docker-extension/ 301 /aws/configuration/localstack-sdks/ /aws/customization/integrations/localstack-sdks/ 301 -/aws/configuration/localsurf/ /aws/customization/networking/localsurf/ 301 +/aws/configuration/localsurf/ /aws/customization/networking/ 301 /aws/configuration/networking/ /aws/customization/networking/ 301 /aws/configuration/security-testing/ /aws/developer-tools/security-testing/ 301 /aws/configuration/security-testing/custom-tls-certificates /aws/developer-tools/security-testing/custom-tls-certificates/ 301 @@ -1087,14 +1074,14 @@ /aws/configuration/security-testing/iam-policy-stream /aws/developer-tools/security-testing/iam-policy-stream/ 301 /aws/configuration/security-testing/iam-policy-stream/ /aws/developer-tools/security-testing/iam-policy-stream/ 301 /aws/configuration/state-management/ /aws/developer-tools/snapshots/ 301 -/aws/configuration/state-management/cli-commands /aws/developer-tools/snapshots/cli-commands/ 301 -/aws/configuration/state-management/cli-commands/ /aws/developer-tools/snapshots/cli-commands/ 301 +/aws/configuration/state-management/cli-commands /aws/developer-tools/running-localstack/lstk/#snapshot 301 +/aws/configuration/state-management/cli-commands/ /aws/developer-tools/running-localstack/lstk/#snapshot 301 /aws/configuration/state-management/cloud-pods /aws/developer-tools/snapshots/cloud-pods/ 301 /aws/configuration/state-management/cloud-pods/ /aws/developer-tools/snapshots/cloud-pods/ 301 -/aws/configuration/state-management/export-import-state /aws/developer-tools/snapshots/export-import-state/ 301 -/aws/configuration/state-management/export-import-state/ /aws/developer-tools/snapshots/export-import-state/ 301 -/aws/configuration/state-management/launchpad /aws/developer-tools/snapshots/launchpad/ 301 -/aws/configuration/state-management/launchpad/ /aws/developer-tools/snapshots/launchpad/ 301 +/aws/configuration/state-management/export-import-state /aws/developer-tools/snapshots/saving-snapshots-locally/ 301 +/aws/configuration/state-management/export-import-state/ /aws/developer-tools/snapshots/saving-snapshots-locally/ 301 +/aws/configuration/state-management/launchpad /aws/developer-tools/snapshots/ 301 +/aws/configuration/state-management/launchpad/ /aws/developer-tools/snapshots/ 301 /aws/configuration/state-management/persistence /aws/developer-tools/snapshots/persistence/ 301 /aws/configuration/state-management/persistence/ /aws/developer-tools/snapshots/persistence/ 301 /aws/configuration/testing-utils/ /aws/customization/integrations/localstack-sdks/testing-utils/ 301 @@ -1130,8 +1117,8 @@ /aws/integrations/containers/openshift/ /aws/customization/kubernetes/openshift/ 301 /aws/integrations/containers/rancher-desktop /aws/customization/other-installations/rancher-desktop/ 301 /aws/integrations/containers/rancher-desktop/ /aws/customization/other-installations/rancher-desktop/ 301 -/aws/integrations/messaging/docker-compose /aws/customization/integrations/app-frameworks/docker-compose/ 301 -/aws/integrations/messaging/docker-compose/ /aws/customization/integrations/app-frameworks/docker-compose/ 301 +/aws/integrations/messaging/docker-compose /aws/customization/other-installations/docker-images/ 301 +/aws/integrations/messaging/docker-compose/ /aws/customization/other-installations/docker-images/ 301 /aws/integrations/messaging /aws/customization/integrations/app-frameworks/ 301 /aws/integrations/messaging/ /aws/customization/integrations/app-frameworks/ 301 /aws/integrations/messaging/selfmanaged-kafka-cluster /aws/customization/integrations/app-frameworks/selfmanaged-kafka-cluster/ 301 @@ -1139,6 +1126,9 @@ /aws/integrations/continuous-integration /aws/ci-pipelines/ 301 /aws/integrations/continuous-integration/ /aws/ci-pipelines/ 301 +/aws/configuration/networking/* /aws/customization/networking/:splat 301 +/aws/configuration/localstack-sdks/* /aws/customization/integrations/localstack-sdks/:splat 301 +/aws/configuration/extensions/* /aws/customization/integrations/extensions/:splat 301 /aws/capabilities/networking/* /aws/customization/networking/:splat 301 /aws/capabilities/extensions/* /aws/customization/integrations/extensions/:splat 301 /aws/capabilities/localstack-sdks/* /aws/customization/integrations/localstack-sdks/:splat 301 diff --git a/public/images/aws/badge-demo.png b/public/images/aws/badge-demo.png deleted file mode 100644 index 4bc3e28d2..000000000 Binary files a/public/images/aws/badge-demo.png and /dev/null differ diff --git a/public/images/aws/link-generator.png b/public/images/aws/link-generator.png deleted file mode 100644 index fc3af5e65..000000000 Binary files a/public/images/aws/link-generator.png and /dev/null differ diff --git a/public/images/aws/ls-not-running.png b/public/images/aws/ls-not-running.png deleted file mode 100644 index f89c31ee2..000000000 Binary files a/public/images/aws/ls-not-running.png and /dev/null differ diff --git a/public/images/aws/merge-strategies.png b/public/images/aws/merge-strategies.png deleted file mode 100644 index 19423119c..000000000 Binary files a/public/images/aws/merge-strategies.png and /dev/null differ diff --git a/public/images/aws/metadata-load-failed.png b/public/images/aws/metadata-load-failed.png deleted file mode 100644 index 9a0ce4d55..000000000 Binary files a/public/images/aws/metadata-load-failed.png and /dev/null differ diff --git a/public/images/aws/persistence-pods-remote.png b/public/images/aws/persistence-pods-remote.png deleted file mode 100644 index 554e584e7..000000000 Binary files a/public/images/aws/persistence-pods-remote.png and /dev/null differ diff --git a/public/images/aws/pods-workflow.png b/public/images/aws/pods-workflow.png new file mode 100644 index 000000000..c732bbaee Binary files /dev/null and b/public/images/aws/pods-workflow.png differ diff --git a/public/images/aws/snapshot-lifecycle-overview.png b/public/images/aws/snapshot-lifecycle-overview.png new file mode 100644 index 000000000..09b03ffe1 Binary files /dev/null and b/public/images/aws/snapshot-lifecycle-overview.png differ diff --git a/public/images/aws/snapshot-merge-account-region.png b/public/images/aws/snapshot-merge-account-region.png new file mode 100644 index 000000000..a054a2a47 Binary files /dev/null and b/public/images/aws/snapshot-merge-account-region.png differ diff --git a/public/images/aws/snapshot-merge-overwrite.png b/public/images/aws/snapshot-merge-overwrite.png new file mode 100644 index 000000000..99ef510bd Binary files /dev/null and b/public/images/aws/snapshot-merge-overwrite.png differ diff --git a/public/images/aws/snapshot-merge-service.png b/public/images/aws/snapshot-merge-service.png new file mode 100644 index 000000000..9f097fc30 Binary files /dev/null and b/public/images/aws/snapshot-merge-service.png differ diff --git a/src/components/SectionCards.astro b/src/components/SectionCards.astro index 61686ee24..06f1fabd9 100644 --- a/src/components/SectionCards.astro +++ b/src/components/SectionCards.astro @@ -7,9 +7,10 @@ interface Props { title?: string; customTitles?: Record; useDirectFiles?: boolean; + excludeFiles?: string[]; } -const { basePath, title, customTitles = {}, useDirectFiles = false } = Astro.props; +const { basePath, title, customTitles = {}, useDirectFiles = false, excludeFiles = [] } = Astro.props; // Get sections - either index files from subdirectories or direct files const allSections = await getCollection('docs', ({ id }) => { @@ -49,14 +50,18 @@ const sortedSections = allSections.sort((a, b) => { return titleA.localeCompare(titleB); }); -const sectionData = sortedSections.map(section => { +const sectionData = sortedSections.flatMap(section => { // Extract the key name from the section ID const relativePath = section.id.substring(basePath.length); const keyName = relativePath.split('/').filter(part => part !== '')[0]; - + // For direct files, we need to remove the file extension from the key const cleanKey = useDirectFiles ? keyName.replace(/\.(md|mdx)$/, '') : keyName; - + + if (excludeFiles.includes(cleanKey)) { + return []; + } + // Use custom title if provided, otherwise fall back to the section title const sectionTitle = customTitles[cleanKey] || section.data.title || section.data.linkTitle || 'Unknown Section'; const description = section.data.description || `Learn more about ${sectionTitle}`; diff --git a/src/content/docs/aws/ci-pipelines/best-practices.mdx b/src/content/docs/aws/ci-pipelines/best-practices.mdx new file mode 100644 index 000000000..399ed3b5c --- /dev/null +++ b/src/content/docs/aws/ci-pipelines/best-practices.mdx @@ -0,0 +1,188 @@ +--- +title: CI Best Practices +description: Commands and general practices for running LocalStack in any CI system, from authentication and tool installation to seeding state and collecting logs. +template: doc +sidebar: + order: 2 +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +Every CI system has its own configuration syntax, runner model, and feature set. +Consult your CI provider's own documentation for how to declare jobs, secrets, caches, and artifacts. +This guide covers the parts that are the same everywhere, such as the LocalStack-specific commands you run, and the best practices for running a LocalStack job. + +Whatever the provider, a CI job follows the same steps: + +1. Expose your CI Auth Token to the job as `LOCALSTACK_AUTH_TOKEN`. +2. Install `lstk` and any tools your tests need, such as the AWS CLI or Terraform. +3. Configure and start the emulator with `lstk start`. +4. Deploy your infrastructure, using an Infrastructure as Code tool. +5. Alternatively, seed state from a snapshot with `lstk load`. +6. Run your tests. +7. Collect the emulator logs as a build artifact. + +## Set your Auth Token + +Every LocalStack CI run needs a [CI Auth Token](https://app.localstack.cloud/workspace/auth-tokens), rather than a personal Developer Auth Token. +Store the token in your CI system as `LOCALSTACK_AUTH_TOKEN`. +Every CI provider offers somewhere to keep sensitive values, and most distinguish secrets from plain environment variables. +Secrets are masked in job logs and withheld from forked-repository builds. +Never commit a token to your repository or paste it into a pipeline definition. + +The `lstk` CLI tool automatically passes the `LOCALSTACK_AUTH_TOKEN` value into the emulator container when it starts. +There is no need to invoke `lstk login`, which is only useful in an interactive session. + +## Install the tools + +Your job needs the `lstk` CLI, plus whichever AWS tooling your tests use. +Many hosted runners already ship Docker, the AWS CLI, and Terraform, so check your runner image before adding an install step. + +### `lstk` + +[`lstk`](/aws/developer-tools/running-localstack/lstk/) is the recommended way to run and manage LocalStack. +It is a single binary, so installing it in CI is quick with tools such as `npm` or `brew`. + + + + +```bash +npm install -g @localstack/lstk +``` + + + + +```bash +brew install localstack/tap/lstk +``` + + + + +See the [`lstk` installation guide](/aws/developer-tools/running-localstack/lstk/#installation) for all installation methods. +`lstk` also needs a working Docker daemon on the runner, with access to a Docker socket so the emulator can spawn its own containers for services such as Lambda and ECS. + +### AWS CLI + +`lstk aws` proxies your host `aws` binary with the LocalStack endpoint, credentials, and region already configured, so the AWS CLI must be installed separately (if not already installed in your CI system). + +Refer to the [AWS CLI installation instructions](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) for details, and to the [AWS CLI guide](/aws/connecting/aws-cli/) for using it against LocalStack. + +### Terraform + +`lstk terraform` drives the real `terraform` binary, so Terraform itself must be on the job's `PATH`. +Install it with your provider's setup step where one exists (for example `hashicorp/setup-terraform` on GitHub Actions), or install it directly. + +Refer to the [Terraform installation instructions](https://developer.hashicorp.com/terraform/install) for details, and to the [Terraform guide](/aws/connecting/infrastructure-as-code/terraform/) for using it against LocalStack. + +## Configure the emulator + +The `lstk` CLI tool uses a `config.toml` file to discover the required configuration parameters when starting the emulator. +Commit a `.lstk/config.toml` to your repository, and both your developers and your CI jobs get the same emulator configuration, with no environment variables to duplicate across pipeline files. +`lstk` picks up `./.lstk/config.toml` automatically when it is run from the root of your source tree: + +```toml +# .lstk/config.toml +[[containers]] +type = "aws" # Emulator type: "aws", "snowflake", or "azure" +tag = "2026.4" # Pin the image tag for reproducible builds +port = "4566" +env = ["ci"] # Apply the [env.ci] profile below + +[env.ci] +DEBUG = "1" +``` + +See the [configuration reference](/aws/developer-tools/running-localstack/lstk/#configuration) for every available field. + +Keep a single `.lstk/config.toml` for local development and CI where you can. +However, if a CI job needs different settings, pass an alternative file with `lstk --config ./ci/lstk.toml start`. + +## Start the emulator + +Start LocalStack with a single command: + +```bash +lstk start +``` + +`lstk start` brings the LocalStack emulator all the way to a ready state. +It pulls the container image if needed, validates your license, starts the container, and returns only once the emulator is ready, so there is no need for a separate wait or health-check step. +If startup fails, the command exits with a non-zero return code, causing your CI job to fail. + +For machine-readable output, add the global `--json` flag to any command. +See [structured output](/aws/developer-tools/running-localstack/lstk/#structured-output) and [exit codes](/aws/developer-tools/running-localstack/lstk/#exit-codes) if your pipeline needs to inspect results programmatically. + +## Seed state from Infrastructure as Code + +Most CI pipelines create the resources their tests need by applying the same Infrastructure as Code they use for production. +The `lstk` proxies automatically point those tools at the emulator, without any explicit configuration. + +For example, with Terraform, run your usual commands through `lstk terraform` (or its `lstk tf` alias): + +```bash +lstk terraform init +lstk terraform apply -auto-approve +``` + +The [`lstk cdk`](/aws/connecting/infrastructure-as-code/aws-cdk/) and [`lstk sam`](/aws/connecting/infrastructure-as-code/aws-sam/) proxies work the same way, and [other IaC tools](/aws/connecting/infrastructure-as-code/) can target the emulator through its endpoint directly. + +## Seed state from a snapshot + +Rather than deploying your whole infrastructure on every run, you can seed the emulator from a [snapshot](/aws/developer-tools/snapshots/) captured earlier, either from a Cloud Pod or from a local snapshot file: + +```bash +# Load a Cloud Pod (requires LOCALSTACK_AUTH_TOKEN) +lstk load pod:my-baseline + +# Load a snapshot file produced by an earlier job +lstk load ./baseline.snapshot +``` + +`lstk load` starts the emulator first, if it is not already running, so it can replace a separate `lstk start` step. +Alternatively, name the snapshot in your config, and `lstk start` loads it for you on every fresh start: + +```toml +[[containers]] +type = "aws" +port = "4566" +snapshot = "pod:my-baseline" +``` + +Override the configured snapshot for a single run with `lstk start --snapshot pod:other-baseline`, or skip auto-loading entirely with `lstk start --no-snapshot`. + +To produce the snapshot in the first place, see [Cloud Pods](/aws/developer-tools/snapshots/cloud-pods/) and [saving snapshots locally](/aws/developer-tools/snapshots/saving-snapshots-locally/). + +## Run your tests + +Once the emulator is running, point your tooling at it. +For Infrastructure as Code tools (such as Terraform), use the `lstk` proxy version of the tool, such as `lstk terraform`. + +For test suites and SDK-based code, either set the endpoint and test credentials in the job's environment: + +```bash +export AWS_ENDPOINT_URL=http://localhost.localstack.cloud:4566 +export AWS_ACCESS_KEY_ID=test +export AWS_SECRET_ACCESS_KEY=test +``` + +Or create a `localstack` AWS profile and select it: + +```bash +lstk setup aws +export AWS_PROFILE=localstack +``` + +See [connecting to LocalStack](/aws/connecting/) for the full set of options. + +## Collect logs + +The emulator container disappears when the job ends, so consider exporting the logs before the test terminates, then store them as a build artifact: + +```bash +lstk logs --verbose > localstack.log +``` + +Run this step even when the tests fail, so you capture the logs regardless of success or failure. To make failures easier to diagnose in the first place, set `DEBUG = "1"` in your CI environment profile. +See [logging](/aws/customization/logging/) for the available log levels. diff --git a/src/content/docs/aws/ci-pipelines/bitbucket.md b/src/content/docs/aws/ci-pipelines/bitbucket.md index 373651189..d9fb05a0f 100644 --- a/src/content/docs/aws/ci-pipelines/bitbucket.md +++ b/src/content/docs/aws/ci-pipelines/bitbucket.md @@ -3,7 +3,7 @@ title: BitBucket description: Use LocalStack in BitBucket Pipelines. template: doc sidebar: - order: 3 + order: 4 --- ## Introduction @@ -11,19 +11,25 @@ sidebar: [BitBucket Pipeline](https://bitbucket.org/product/features/pipelines) is a CI/CD tool that allows you to build, test, and deploy your code directly from BitBucket. This guide will show you how to use LocalStack in BitBucket Pipelines. +BitBucket runs your build and the Docker daemon in separate containers, and does not support mounting volumes. +This guide therefore starts the LocalStack container directly with `docker run`, so the pipeline controls the port mappings and the Docker connection itself, and then uses the [`lstk`](/aws/developer-tools/running-localstack/lstk/) tool proxies to interact with it. +On CI systems without those constraints, `lstk` can manage the container lifecycle as well; see [CI Best Practices](/aws/ci-pipelines/best-practices/). + ## Setting up the BitBucket Pipeline When you want to integrate LocalStack into your job configuration, you just have to execute the following steps: - Specify the Docker Socket to allow the LocalStack container to access the Docker daemon. -- Export the `AWS_ENDPOINT_URL` environment variable to point to the LocalStack endpoint. -- Install the `localstack` CLI and `awscli-local` to interact with LocalStack's emulated services. +- Pass your CI Auth Token to the container, which is required to start the emulator. +- Export the `LSTK_ENDPOINT_URL` environment variable to point `lstk` at the LocalStack endpoint. +- Install the AWS CLI and `lstk` to interact with LocalStack's emulated services. - Start the LocalStack container in detached mode by specifying the Docker Socket and Docker Host. +- Wait for the emulator to become ready before using it. The following example BitBucket Pipeline configuration (`bitbucket-pipelines.yaml`) executes these steps, creates a new S3 bucket, and queries the list of S3 buckets: ```yaml showshowLineNumbers -image: python:3.9 +image: node:22 definitions: services: @@ -37,26 +43,25 @@ pipelines: services: - docker script: - - export PYTHONPATH=$PYTHONPATH:$(pwd) - export DOCKER_SOCK=$DOCKER_HOST - - export AWS_ENDPOINT_URL="http://localhost.localstack.cloud:4566" - - env + - export LSTK_ENDPOINT_URL="http://localhost.localstack.cloud:4566" - echo "${BITBUCKET_DOCKER_HOST_INTERNAL} localhost.localstack.cloud " >> /etc/hosts - - pip install localstack awscli-local + - apt-get update && apt-get install -y awscli + - npm install -g @localstack/lstk + - docker run -d --rm -p 4566:4566 -p 4510-4559:4510-4559 -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} -e DEBUG=1 -e DOCKER_SOCK=tcp://${BITBUCKET_DOCKER_HOST_INTERNAL}:2375 -e DOCKER_HOST=tcp://${BITBUCKET_DOCKER_HOST_INTERNAL}:2375 --name localstack-aws localstack/localstack-pro - | - curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" - unzip awscliv2.zip - ./aws/install - - docker run -d --rm -p 4566:4566 -p 4510-4559:4510-4559 -e DOCKER_SOCK=tcp://${BITBUCKET_DOCKER_HOST_INTERNAL}:2375 -e DOCKER_HOST=tcp://${BITBUCKET_DOCKER_HOST_INTERNAL}:2375 --name localstack-main localstack/localstack - - localstack wait -t 60 - - awslocal s3 mb s3://test-bucket - - awslocal s3 ls + for _ in $(seq 1 60); do + curl -sf "${LSTK_ENDPOINT_URL}/_localstack/health" > /dev/null && break + sleep 2 + done + - lstk aws s3 mb s3://test-bucket + - lstk aws s3 ls ``` ## Configuring a CI Auth Token -You can enable LocalStack for AWS by using the `localstack/localstack-pro` image and adding your CI Auth Token to the project's environment variables. -The LocalStack container will automatically pick it up and activate the Pro features. +For the configuration above to work, add your CI Auth Token to the project's environment variables. +The LocalStack container will automatically pick it up and activate your LocalStack license. Go to the [CI Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) and copy your CI Auth Token. To add a CI Auth Token to your BitBucket Pipeline: @@ -65,24 +70,7 @@ To add a CI Auth Token to your BitBucket Pipeline: - Select the **Settings** on the top navigation bar. - Select **Workspace settings** from the **Settings dropdown** menu. - On the left-hand menu, navigate to **Pipelines** and click on **Workspace variables**. -- Add a new variable with the name `LOCALSTACK_AUTH_TOKEN` and the value of your CI Auth Token. - -Navigate to your BitBucket Pipeline and add the following lines to the `bitbucket-pipelines.yaml` file: - -```yaml showshowLineNumbers -pipelines: - default: - - step: - name: Test Localstack - services: - - docker - script: - ... - - export LOCALSTACK_AUTH_TOKEN=$LOCALSTACK_AUTH_TOKEN - ... - - docker run -d --rm -p 4566:4566 -p 4510-4559:4510-4559 -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} -e DEBUG=1 -e LS_LOG=trace -e DOCKER_SOCK=tcp://${BITBUCKET_DOCKER_HOST_INTERNAL}:2375 -e DOCKER_HOST=tcp://${BITBUCKET_DOCKER_HOST_INTERNAL}:2375 --name localstack-main localstack/localstack-pro - ... -``` +- Add a new variable with the name `LOCALSTACK_AUTH_TOKEN` and the value of your CI Auth Token, and mark it as **Secured**. ## Current Limitations diff --git a/src/content/docs/aws/ci-pipelines/circleci.md b/src/content/docs/aws/ci-pipelines/circleci.md index f304bbd80..226cfd959 100644 --- a/src/content/docs/aws/ci-pipelines/circleci.md +++ b/src/content/docs/aws/ci-pipelines/circleci.md @@ -3,94 +3,55 @@ title: CircleCI description: Use LocalStack in CircleCI. template: doc sidebar: - order: 2 + order: 3 --- ## Introduction [CircleCI](https://circleci.com) is a continuous integration and continuous delivery (CI/CD) platform which uses a configuration file (usually named `.circleci/config.yml`) to define the build, test, and deployment workflows. -This guide shows how to run LocalStack in CircleCI using the LocalStack Docker image and the LocalStack CLI. +This guide shows how to run LocalStack in CircleCI using the [`lstk` CLI](/aws/developer-tools/running-localstack/lstk/). ## Snippets ### Start up LocalStack -#### Default - ```yaml showshowLineNumbers version: '2.1' -orbs: - python: circleci/python@4.0.0 jobs: localstack-test: machine: image: ubuntu-2204:current steps: - checkout + # LOCALSTACK_AUTH_TOKEN comes from the project's environment variables - run: - name: Install LocalStack CLI and awslocal - command: | - python3 -m pip install --user --upgrade pip - python3 -m pip install --user localstack awscli-local[ver1] - echo 'export PATH=$HOME/.local/bin:$PATH' >> "$BASH_ENV" + name: Install lstk + command: npm install -g @localstack/lstk + - run: + name: Configure the AWS profile + command: lstk setup aws - run: name: Start LocalStack - command: | - source "$BASH_ENV" - docker pull localstack/localstack:latest - localstack start -d - localstack wait -t 60 + command: lstk start - run: name: Test LocalStack command: | - awslocal s3 mb s3://test-bucket - awslocal s3 ls + lstk aws s3 mb s3://test-bucket + lstk aws s3 ls workflows: localstack-test: jobs: - localstack-test ``` -#### Async - -```yaml showshowLineNumbers -version: '2.1' -orbs: - python: circleci/python@4.0.0 -jobs: - localstack-test: - machine: - image: ubuntu-2204:current - steps: - - checkout - - run: - name: Install LocalStack CLI and awslocal - command: | - python3 -m pip install --user --upgrade pip - python3 -m pip install --user localstack awscli-local[ver1] - echo 'export PATH=$HOME/.local/bin:$PATH' >> "$BASH_ENV" - - run: - name: Start LocalStack in background - command: | - source "$BASH_ENV" - docker pull localstack/localstack:latest - localstack start -d - - run: - name: Execute setup and tests - command: | - source "$BASH_ENV" - localstack wait -t 60 - awslocal sqs create-queue --queue-name test-queue - awslocal sqs list-queues -workflows: - localstack-test: - jobs: - - localstack-test -``` +`lstk start` pulls the image, validates your license, and returns only once the emulator is ready, so no separate wait step is needed. +`lstk aws` proxies the `aws` binary with LocalStack's endpoint and credentials applied, so the AWS CLI must be available on the runner; add an install step if your image does not provide it. +`lstk setup aws` writes a `localstack` AWS profile for that binary to use. It is optional, but without it `lstk` notes on every call that no profile was found. ### Configuration To configure LocalStack use the `environment` key on the job level or a shell command, where the latter takes higher precedence. +`lstk start` forwards host environment variables prefixed with `LOCALSTACK_` into the container, which strips the prefix, so set `LOCALSTACK_DEBUG` to control the container's `DEBUG` option. Read more about the [configuration options](/aws/customization/configuration-options) of LocalStack. @@ -103,11 +64,11 @@ jobs: machine: image: ubuntu-2204:current environment: - DEBUG: 1 - LS_LOG: trace + LOCALSTACK_DEBUG: "1" + LOCALSTACK_LS_LOG: "trace" steps: ... - - run: localstack start -d + - run: lstk start ... ``` @@ -123,15 +84,15 @@ jobs: - run: name: Configure LocalStack command: | - echo 'export DEBUG=1' >> "$BASH_ENV" - echo 'export LS_LOG=trace' >> "$BASH_ENV" + echo 'export LOCALSTACK_DEBUG=1' >> "$BASH_ENV" + echo 'export LOCALSTACK_LS_LOG=trace' >> "$BASH_ENV" ... ``` ### Configuring a CI Auth Token To enable LocalStack for AWS, you need to add your LocalStack CI Auth Token to the project's environment variables. -The LocalStack container will automatically pick it up and activate the licensed features. +`lstk` will automatically pick it up and activate the licensed features. Go to the [CI Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) and copy your CI Auth Token. To add the CI Auth Token to your CircleCI project, follow these steps: @@ -144,38 +105,6 @@ To add the CI Auth Token to your CircleCI project, follow these steps: After adding the variable, CircleCI injects `LOCALSTACK_AUTH_TOKEN` into your job environment. -```yaml showshowLineNumbers -version: '2.1' -orbs: - python: circleci/python@4.0.0 -jobs: - localstack-test: - machine: - image: ubuntu-2204:current - steps: - - checkout - - run: - name: Install LocalStack CLI and awslocal - command: | - python3 -m pip install --user --upgrade pip - python3 -m pip install --user localstack awscli-local[ver1] - echo 'export PATH=$HOME/.local/bin:$PATH' >> "$BASH_ENV" - - run: - name: Start LocalStack - command: | - source "$BASH_ENV" - docker pull localstack/localstack:latest - localstack start -d - localstack wait -t 60 - - run: - name: Verify LocalStack setup - command: localstack logs | rg "activated|auth token|ready" -workflows: - localstack-test: - jobs: - - localstack-test -``` - ### Dump LocalStack logs ```yaml showshowLineNumbers @@ -188,7 +117,8 @@ jobs: ... - run: name: Dump LocalStack logs - command: localstack logs | tee localstack.log + when: always + command: lstk logs --verbose | tee localstack.log - store_artifacts: path: localstack.log name: localstack-logs @@ -222,21 +152,18 @@ jobs: image: ubuntu-2204:current steps: - - run: python3 -m pip install localstack awscli-local[ver1] - - run: | - docker pull localstack/localstack:latest - localstack start -d - localstack wait -t 60 + - run: npm install -g @localstack/lstk + - run: lstk start ... - run: name: Load state if exists - command: localstack pod load || true + command: lstk load pod: || true ... # Deploy infrastructure changes ... - run: name: Save Cloud Pod - command: localstack pod save + command: lstk save pod: workflows: @@ -255,15 +182,12 @@ jobs: image: ubuntu-2204:current steps: - - run: python3 -m pip install localstack awscli-local[ver1] - - run: | - docker pull localstack/localstack:latest - localstack start -d - localstack wait -t 60 + - run: npm install -g @localstack/lstk + - run: lstk start ... - run: name: Load Cloud Pod - command: localstack pod load + command: lstk load pod: ... # Run some tests @@ -302,21 +226,18 @@ jobs: image: ubuntu-2204:current steps: - - run: python3 -m pip install localstack awscli-local[ver1] - - run: | - docker pull localstack/localstack:latest - localstack start -d - localstack wait -t 60 + - run: npm install -g @localstack/lstk + - run: lstk start ... - run: name: Load Cloud Pod - command: localstack pod load || true + command: lstk load pod: || true ... # Deploy infrastructure ... - run: name: Save Cloud Pod - command: localstack pod save + command: lstk save pod: - run: name: Trigger other workflows # Replace placeholders with right values @@ -333,15 +254,12 @@ jobs: image: ubuntu-2204:current steps: - - run: python3 -m pip install localstack awscli-local[ver1] - - run: | - docker pull localstack/localstack:latest - localstack start -d - localstack wait -t 60 + - run: npm install -g @localstack/lstk + - run: lstk start ... - run: name: Load state if exists - command: localstack pod load || true + command: lstk load pod: || true ... @@ -362,110 +280,6 @@ workflows: ... ``` -#### Ephemeral Instance (Preview) - -Find out more about [Ephemeral Instances](/aws/developer-tools/cloud-sandbox/ephemeral-instances). - -##### Same job - -```yaml showshowLineNumbers -... -jobs: - do-work: - machine: - image: ubuntu-2204:current - steps: - - run: - name: Create Ephemeral Instance - command: | - response=$(curl -X POST \ - -H "ls-api-key: $LOCALSTACK_AUTH_TOKEN" \ - -H "authorization: token $LOCALSTACK_AUTH_TOKEN" \ - -H "content-type: application/json" \ - -d '{"auto_load_pod":"false"}' \ - https://api.localstack.cloud/v1/previews/my-circleci-state) - endpoint_url=$(echo "$response" | jq -r '.endpointUrl') - if [ -z "$endpoint_url" ] || [ "$endpoint_url" = "null" ]; then - echo "Unable to create preview environment. API response: $response" - exit 1 - fi - echo "export AWS_ENDPOINT_URL=$endpoint_url" >> "$BASH_ENV" - - run: - name: Output the ephemeral instance address - command: echo "$AWS_ENDPOINT_URL" -... -workflows: - use-ephemeral-instance: - jobs: - - do-work -... -``` - -##### Multiple jobs - -```yaml showshowLineNumbers -... -jobs: - setup-instance: - machine: - image: ubuntu-2204:current - steps: - - run: - name: Create Ephemeral Instance - command: | - response=$(curl -X POST \ - -H "ls-api-key: $LOCALSTACK_AUTH_TOKEN" \ - -H "authorization: token $LOCALSTACK_AUTH_TOKEN" \ - -H "content-type: application/json" \ - -d '{"auto_load_pod":"false"}' \ - https://api.localstack.cloud/v1/previews/my-circleci-state) - endpoint_url=$(echo "$response" | jq -r '.endpointUrl') - if [ -z "$endpoint_url" ] || [ "$endpoint_url" = "null" ]; then - echo "Unable to create preview environment. API response: $response" - exit 1 - fi - echo "export AWS_ENDPOINT_URL=$endpoint_url" >> ls-env-vars - - run: - name: Persist AWS Endpoint URL - command: cat ls-env-vars - - persist_to_workspace: - root: . - paths: - - ls-env-vars - - run-test: - machine: - image: ubuntu-2204:current - steps: - - attach_workspace: - at: . - - run: - name: Set up LS env variables - command: cat ./ls-env-vars >> $BASH_ENV - - run: - name: Output the ephemeral instance address - command: echo "$AWS_ENDPOINT_URL" -... - # Run any logic against the Ephemeral Instance, - # then stop when not needed anymore - - run: - name: Stop Ephemeral Instance - command: | - # Replace with the id returned by the API in setup-instance. - curl -X DELETE \ - -H "ls-api-key: $LOCALSTACK_AUTH_TOKEN" \ - -H "authorization: token $LOCALSTACK_AUTH_TOKEN" \ - https://api.localstack.cloud/v1/previews/ - -... -workflows: - use-ephemeral-instance: - jobs: - - setup-instance - - run-test -... -``` - #### Workspace This strategy persist LocalStack's state between jobs for the current workflow. @@ -477,41 +291,37 @@ jobs: machine: image: ubuntu-2204:current steps: - - run: python3 -m pip install localstack awscli-local[ver1] - - run: | - docker pull localstack/localstack:latest - localstack start -d - localstack wait -t 60 + - run: npm install -g @localstack/lstk + - run: lstk start ... # LocalStack already running and deployed infrastructure - run: - name: Export state - command: localstack state export ls-state.zip + name: Save a snapshot + command: lstk save ./ls-state.snapshot - persist_to_workspace: - paths: - - ls-state.zip + paths: + - ls-state.snapshot # Store state as artifact for local debugging - - store_artifact: - key: ls-state - paths: ls-state.zip + - store_artifacts: + path: ls-state.snapshot + name: ls-state ... localstack-load-state: machine: image: ubuntu-2204:current steps: - - run: python3 -m pip install localstack awscli-local[ver1] - - run: | - docker pull localstack/localstack:latest - localstack start -d - localstack wait -t 60 + - run: npm install -g @localstack/lstk + - run: lstk start ... # LocalStack already running - attach_workspace: at: . - run: - name: Import state + name: Load the snapshot command: | - test -f ls-state.zip && localstack state import ls-state.zip + if [ -f ls-state.snapshot ]; then + lstk load ./ls-state.snapshot --merge=overwrite + fi ... workflows: localstack-build: @@ -520,7 +330,7 @@ jobs: - localstack-load-state ``` -More information about Localstack's [state import/export](/aws/developer-tools/snapshots/export-import-state). +More information about Localstack's [snapshots](/aws/developer-tools/snapshots/saving-snapshots-locally). #### Cache @@ -534,11 +344,8 @@ jobs: machine: image: ubuntu-2204:current steps: - - run: python3 -m pip install localstack awscli-local[ver1] - - run: | - docker pull localstack/localstack:latest - localstack start -d - localstack wait -t 60 + - run: npm install -g @localstack/lstk + - run: lstk start ... # LocalStack already running # Let's restore previous workflow run's LocalStack state @@ -546,34 +353,37 @@ jobs: # Use latest "ls-state" prefixed cache key: ls-state- - run: - name: Import state - command: test -f ls-state.zip && localstack state import ls-state.zip + name: Load the snapshot + command: | + if [ -f ls-state.snapshot ]; then + lstk load ./ls-state.snapshot --merge=overwrite + fi ... # Infrastructure had been updated # Let's update cached LocalStack state - run: - name: Export state - command: localstack state export ls-state.zip + name: Save a snapshot + command: lstk save ./ls-state.snapshot - save_cache: - key: ls-state-{{checksum ls-state.zip}} - paths: ls-state.zip + key: ls-state-{{checksum ls-state.snapshot}} + paths: ls-state.snapshot ... localstack-do-work: machine: image: ubuntu-2204:current steps: - - run: python3 -m pip install localstack awscli-local[ver1] - - run: | - docker pull localstack/localstack:latest - localstack start -d - localstack wait -t 60 + - run: npm install -g @localstack/lstk + - run: lstk start # LocalStack already running - restore_cache: # Use latest "ls-state" prefixed cache key: ls-state- - run: - name: Import state - command: test -f ls-state.zip && localstack state import ls-state.zip + name: Load the snapshot + command: | + if [ -f ls-state.snapshot ]; then + lstk load ./ls-state.snapshot --merge=overwrite + fi ... @@ -586,4 +396,4 @@ workflows: ... ``` -More information about [state management](/aws/developer-tools/snapshots/export-import-state). \ No newline at end of file +More information about [snapshots](/aws/developer-tools/snapshots/saving-snapshots-locally). \ No newline at end of file diff --git a/src/content/docs/aws/ci-pipelines/codebuild.md b/src/content/docs/aws/ci-pipelines/codebuild.md index f4e7060e8..da4a04aeb 100644 --- a/src/content/docs/aws/ci-pipelines/codebuild.md +++ b/src/content/docs/aws/ci-pipelines/codebuild.md @@ -3,14 +3,16 @@ title: CodeBuild description: Use LocalStack in CodeBuild. template: doc sidebar: - order: 6 + order: 7 --- ## Introduction [AWS CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/welcome.html) is a managed AWS service for the build and testing phases of software development. CodeBuild allows you to define your build project, set the source code location, and handles the building and testing, while supporting various programming languages, build tools, and runtime environments. -LocalStack supports CodeBuild out of the box and can be easily integrated into your pipeline to run your tests against a cloud emulator. +This guide shows how to run LocalStack in CodeBuild using the [`lstk` CLI](/aws/developer-tools/running-localstack/lstk/). + +The CodeBuild standard images already provide Docker, Node.js, and the AWS CLI, so `lstk` is the only part that needs installing. :::note LocalStack depends on the Docker socket to emulate your infrastructure. @@ -19,133 +21,68 @@ To enable it, update your project by ticking **Environment > Additional Configur ## Snippets -CodeBuild has the capability to use LocalStack's GitHub Action. - ### Start up LocalStack -#### Native Runner +LocalStack requires a CI Auth Token to run. +Go to the [CI Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) and copy your CI Auth Token, then add it to the project's environment variables: -```yml showshowLineNumbers -version: 0.2 -... -phases: - pre_build: - commands: - - pip3 install localstack awscli - - docker pull public.ecr.aws/localstack/localstack:latest - - localstack start -d - - localstack wait -t 30 -``` +- Navigate to your project dashboard, click **Edit** to open the dropdown, and select **Environment**. +- Click on **Additional configuration** and navigate to the **Environment variables** section. +- Specify **Name** as `LOCALSTACK_AUTH_TOKEN` and **Value** as your CI Auth Token. +Specify **Type** as per your requirement. +- Click on **Update environment** to save your environment variables. -#### GitHub Actions Runner +`lstk` automatically recognizes the token and activates the licensed features. +You can then install `lstk` and start the emulator in your buildspec file: ```yml showshowLineNumbers version: 0.2 phases: + install: + runtime-versions: + nodejs: 22 + commands: + - npm install -g @localstack/lstk pre_build: - steps: - - run: docker pull public.ecr.aws/localstack/localstack:latest - - run: docker image tag public.ecr.aws/localstack/localstack-pro:latest localstack/localstack:latest - - name: Start LocalStack - uses: LocalStack/setup-localstack@v0.2.2 - with: - image-tag: 'latest' - install-awslocal: 'true' + commands: + # LOCALSTACK_AUTH_TOKEN comes from the project's environment variables + - lstk setup aws + - lstk start + build: + commands: + - lstk aws s3 mb s3://test-bucket + - lstk aws s3 ls ``` -### Configuration +`lstk start` pulls the image, validates your license, and returns only once the emulator is ready, so no separate wait step is needed. +`lstk aws` proxies the runner's `aws` binary with LocalStack's endpoint and credentials applied. +`lstk setup aws` writes a `localstack` AWS profile for that binary to use. -Get know more about the LocalStack [config options](/aws/customization/configuration-options). - -#### Native Runner - -```yml showshowLineNumbers -version: 0.2 - -env: - variables: - DEBUG: 1 -... -phases: -... -``` +### Configuration -#### GitHub Actions Runner +To set LocalStack configuration options, pass them as `LOCALSTACK_`-prefixed environment variables. +`lstk start` forwards those into the container which strips the prefix, so `LOCALSTACK_DEBUG` sets the container's `DEBUG` option. ```yml showshowLineNumbers version: 0.2 env: variables: - DEBUG: 1 + LOCALSTACK_DEBUG: "1" + LOCALSTACK_LS_LOG: "trace" ... - phases: - pre_build: - steps: - ... - - name: Start LocalStack - uses: LocalStack/setup-localstack@v0.2.2 - with: - image-tag: 'latest' - configuration: LS_LOG=trace ... ``` -### Configuring a CI Auth Token - -To enable LocalStack for AWS features, you need to add your LocalStack CI Auth Token to the project's environment variables. -The LocalStack container will automatically pick it up and activate the licensed features. - -Go to the [CI Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) and copy your CI Auth Token. -To add the CI Auth Token to your CodeBuild project, follow these steps: - -- Navigate to your project dashboard, click **Edit** to open the dropdown, and select **Environment**. -- Click on **Additional configuration** and navigate to the **Environment variables** section. -- Specify **Name** as `LOCALSTACK_AUTH_TOKEN` and **Value** as your CI Auth Token. -Specify **Type** as per your requirement. - -Click on **Update environment** to save your environment variables. -Navigate to the buildspec file and change the Docker image to `public.ecr.aws/localstack/localstack-pro:latest`: - -#### Native Runner - -```yaml showshowLineNumbers -... -phases: - pre_build: - commands: - - pip3 install localstack awscli - - docker pull public.ecr.aws/localstack/localstack-pro:latest -... -``` - -#### GitHub Actions Runner - -```yml showshowLineNumbers -... -phases: - pre_build: - steps: - - run: docker pull public.ecr.aws/localstack/localstack-pro:latest - - run: docker image tag public.ecr.aws/localstack/localstack-pro:latest localstack/localstack-pro:latest - - name: Start LocalStack - uses: LocalStack/setup-localstack@v0.2.2 - with: - image-tag: 'latest' - use-pro: 'true' -... -``` +Settings that apply to every run belong in an [`[env.*]` profile](/aws/developer-tools/running-localstack/lstk/#configuration) in a `.lstk/config.toml` committed to your repository, which also lets you pin the image tag. +Read more about the [configuration options](/aws/customization/configuration-options) of LocalStack. ### Dump LocalStack logs ```yaml showshowLineNumbers ... -artifacts: - files: - - localstack.log - phases: pre_build: commands: @@ -158,21 +95,21 @@ phases: post_build: commands: # Dump logs on build fail - - '[ ${CODEBUILD_BUILD_SUCCEEDING:-0} -eq 0 ] (localstack logs | tee localstack.log) || true' + - '[ ${CODEBUILD_BUILD_SUCCEEDING:-0} -eq 0 ] && (lstk logs --verbose | tee localstack.log) || true' ... # Optionally store dumped logs as artifact -artifact: +artifacts: files: - localstack.log ``` ### Store LocalStack state -#### Cloud Pods +You can preserve your AWS infrastructure with LocalStack in various ways. -Find more information about cloud pods [here](/aws/developer-tools/snapshots/cloud-pods). +#### Cloud Pods -##### Native Runner +Find more information about Cloud Pods [here](/aws/developer-tools/snapshots/cloud-pods). ```yml showshowLineNumbers ... @@ -181,92 +118,47 @@ phases: commands: ... # LocalStack is up and running already - - localstack pod load || true + # Allow the load to fail as the pod does not exist at first run + - lstk load pod: || true ... - - localstack pod save + - lstk save pod: ... ``` -##### GitHub Actions Runner +#### Artifact -```yml showshowLineNumbers -... -phases: - pre_build: - steps: - # LocalStack is up and running already - - name: Load the Cloud Pod - continue-on-error: true # Allow it to fail as pod does not exist at first run - uses: LocalStack/setup-localstack@v0.2.2 - with: - state-backend: cloud-pods - name: - action: load - skip-startup: 'true' - ... - - name: Save the Cloud Pod - uses: LocalStack/setup-localstack@v0.2.2 - with: - state-backend: cloud-pods - state-name: - ... -``` +Instead of the LocalStack platform, you can keep the state as a local snapshot file and move it between builds with CodeBuild's own artifact storage. -#### Ephemeral Instances (Preview) +Find out more about [snapshots](/aws/developer-tools/snapshots/saving-snapshots-locally/). ```yml showshowLineNumbers ... phases: pre_build: commands: - ... + # LocalStack is up and running already - | - response=$(curl -X POST -d '{"auto_load_pod": "false"}' \ - -H 'ls-api-key: $LOCALSTACK_API_KEY' \ - -H 'authorization: token $LOCALSTACK_API_KEY' \ - -H 'content-type: application/json' \ - https://api.localstack.cloud/v1/previews/my-localstack-state) - - if [ "$endpointUrl" = "null" ] || [ "$endpointUrl" = "" ]; then - echo "Unable to create preview environment. API response: $response" - exit 1 - fi - echo "Created preview environment with endpoint URL: $endpointUrl" - - export AWS_ENDPOINT_URL=$endpointUrl + if [ -f ls-state.snapshot ]; then + lstk load ./ls-state.snapshot --merge=overwrite + fi ... -``` - -Find out more about [ephemeral instances](/aws/developer-tools/cloud-sandbox/ephemeral-instances). - -#### Artifact - -Find out more about [state management](/aws/developer-tools/snapshots/export-import-state/). - -```yml showshowLineNumbers + - lstk save ./ls-state.snapshot ... -phases: - pre_build: - # LocalStack is up and running already - - (test -f ./ls-state-pod.zip && localstack state import ./ls-state-pod.zip) || true - ... - - localstack state export ./ls-state-pod.zip -... -artifact: +artifacts: files: - - ls-state-pod.zip + - ls-state.snapshot ``` Alternatively save as a secondary artifact: ```yml showshowLineNumbers ... -artifact: +artifacts: ... secondary-artifacts: ls-state: files: - - ls-state-pod.zip + - ls-state.snapshot ... ``` @@ -274,54 +166,43 @@ To use previously stored artifacts as inputs, set them as a source in the projec #### Cache -Additional information about [state export and import](/aws/developer-tools/snapshots/export-import-state/). - -##### Native Runner - ```yml showshowLineNumbers ... phases: pre_build: commands: - # LocalStack is up and running already - - (test -f ./ls-state-pod.zip && localstack state import ./ls-state-pod.zip) || true - ... - - localstack state export ./ls-state-pod.zip -... -cache: - paths: - - 'ls-state-pod.zip' -``` - -##### GitHub Actions Runner - -```yml showshowLineNumbers -... -phases: - pre_build: - steps: - - run: (test -f ./ls-state-pod.zip && localstack state import ./ls-state-pod.zip) || true + # LocalStack is up and running already + - | + if [ -f ls-state.snapshot ]; then + lstk load ./ls-state.snapshot --merge=overwrite + fi ... - - run: localstack state export ./ls-state-pod.zip + - lstk save ./ls-state.snapshot ... cache: paths: - - 'ls-state-pod.zip' + - 'ls-state.snapshot' ``` ## Current Limitations -- We recommend using the `public.ecr.aws/localstack/localstack:latest` image to start LocalStack, instead of the `localstack/localstack:latest` image. - LocalStack mirrors the Docker Hub image to the public ECR repository. - You can use the Docker Hub image as well, though you may run into the following error: +- `lstk` pulls the emulator image from Docker Hub by default, where you may run into the following error: ```bash toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit ``` - To resolve this use your Docker Hub account credentials to pull the image. + To resolve this, either use your Docker Hub account credentials to pull the image, or point `lstk` at LocalStack's public ECR mirror with the [`image` field](/aws/developer-tools/running-localstack/lstk/#custom-container-image) in `.lstk/config.toml`: + + ```toml + [[containers]] + type = "aws" + port = "4566" + image = "public.ecr.aws/localstack/localstack-pro" + tag = "latest" + ``` + - LocalStack depends on the Docker socket to emulate your infrastructure. To enable it, update your project by ticking **Environment > Additional Configuration > Privileged > Enable this flag if you want to build Docker Images or want your builds to get elevated privileges**. -- AWS states in its [documentation](https://docs.aws.amazon.com/codebuild/latest/userguide/action-runner-buildspec.html#action-runner-limitations) GitHub Actions Runners are not available for **webhook triggered open Git repositories**. -- Be aware that you can only use either the _Native Runner_ or the _GitHub Actions Runner_ snippets in the same phase -For further information see the official CodeBuild [documentation](https://docs.aws.amazon.com/codebuild/latest/userguide/action-runner-buildspec.html). \ No newline at end of file + +For further information see the official CodeBuild [documentation](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html). diff --git a/src/content/docs/aws/ci-pipelines/github-actions.md b/src/content/docs/aws/ci-pipelines/github-actions.md index 64ad9fa55..e739ee38e 100644 --- a/src/content/docs/aws/ci-pipelines/github-actions.md +++ b/src/content/docs/aws/ci-pipelines/github-actions.md @@ -3,43 +3,25 @@ title: GitHub Actions description: Use LocalStack in GitHub Actions. template: doc sidebar: - order: 4 + order: 5 --- -This page contains easily customisable snippets to show you how to manage LocalStack in a GitHub Actions pipeline. +This page contains easily customizable snippets to show you how to manage LocalStack in a GitHub Actions pipeline. -## Snippets - -### Start up Localstack - -```yaml showshowLineNumbers -- name: Start LocalStack - uses: LocalStack/setup-localstack@v0.2.2 - with: - image-tag: 'latest' - install-awslocal: 'true' -``` - -### Configuration - -To set LocalStack configuration options, you can use the `configuration` input parameter. -For example, to set the `DEBUG` configuration option, you can use the following configuration: +The GitHub-hosted `ubuntu-latest` runner already provides Docker, Node.js, and the AWS CLI, so `lstk` is the only part that needs installing. +On a self-hosted runner, add install steps for whichever of those are missing. -```yml showshowLineNumbers -- name: Start LocalStack - uses: LocalStack/setup-localstack@v0.2.2 - with: - image-tag: 'latest' - install-awslocal: 'true' - configuration: DEBUG=1 -``` +:::caution +The [`LocalStack/setup-localstack`](https://github.com/localstack/setup-localstack) action is no longer supported with `lstk`. +Install and drive [`lstk`](/aws/developer-tools/running-localstack/lstk/) directly in a `run` step, as shown in the snippets below. +::: -You can add extra configuration options by separating them with a comma. +## Snippets -### Configure a CI Auth Token +### Start up Localstack To enable LocalStack for AWS, you need to add your LocalStack CI Auth Token to the project's environment variables. -The LocalStack container will automatically pick it up and activate the licensed features. +`lstk` will automatically pick it up and activate the licensed features. Go to the [CI Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) and copy your CI Auth Token. To add the CI Auth Token to your GitHub project, follow these steps: @@ -48,27 +30,54 @@ To add the CI Auth Token to your GitHub project, follow these steps: - Enter `LOCALSTACK_AUTH_TOKEN` as the name of the secret and paste your CI Auth Token as the value. Click **Add secret** to save your secret. -You can then use our [`setup-localstack`](https://github.com/localstack/setup-localstack) GitHub Action to start your LocalStack container, with the `LOCALSTACK_AUTH_TOKEN` environment variable: +You can then install `lstk` and start the emulator, passing the secret to the step: ```yaml showshowLineNumbers +- name: Install lstk + run: npm install -g @localstack/lstk + +- name: Configure the AWS profile + run: lstk setup aws + - name: Start LocalStack - uses: LocalStack/setup-localstack@v0.2.3 - with: - image-tag: 'latest' - install-awslocal: 'true' - use-pro: 'true' + run: lstk start + env: + LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }} +``` + +`lstk start` pulls the image, validates your license, and returns only once the emulator is ready, so no separate wait step is needed. +To pin the image tag, commit a [`.lstk/config.toml`](/aws/developer-tools/running-localstack/lstk/#configuration) to your repository rather than passing it on the command line. +Where several steps run `lstk`, set `LOCALSTACK_AUTH_TOKEN` once at the job level instead of repeating it on every step. +`lstk setup aws` writes a `localstack` AWS profile for the runner's `aws` binary to use. It is optional, but without it `lstk` notes on every call that no profile was found. + +### Configuration + +To set LocalStack configuration options, pass them as `LOCALSTACK_`-prefixed environment variables. +`lstk start` forwards those into the container, which strips the prefix, so `LOCALSTACK_DEBUG` sets the container's `DEBUG` option. +For example: + +```yml showshowLineNumbers +- name: Start LocalStack + run: lstk start env: LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }} + LOCALSTACK_DEBUG: "1" ``` +You can add extra configuration options as further `LOCALSTACK_`-prefixed variables. +Settings that apply to every run belong in an [`[env.*]` profile](/aws/developer-tools/running-localstack/lstk/#configuration) in `.lstk/config.toml` instead. + ### Dump Localstack logs ```yaml showshowLineNumbers - name: Show localstack logs + if: always() run: | - localstack logs | tee localstack.log + lstk logs --verbose | tee localstack.log ``` +`if: always()` makes the step run even after a failing test, which is when the logs matter most. + ### Store Localstack state You can preserve your AWS infrastructure with Localstack in various ways. @@ -78,24 +87,15 @@ You can preserve your AWS infrastructure with Localstack in various ways. ```yaml showshowLineNumbers ... # Localstack is up and running already -- name: Load the Cloud Pod +- name: Load the Cloud Pod continue-on-error: true # Allow it to fail as pod does not exist at first run - uses: LocalStack/setup-localstack@v0.2.2 - with: - state-backend: cloud-pods - state-name: - state-action: load - skip-startup: 'true' + run: lstk load pod: env: LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }} ... -- name: Save the Cloud Pod - uses: LocalStack/setup-localstack@v0.2.2 - with: - state-backend: cloud-pods - state-name: - state-action: save +- name: Save the Cloud Pod + run: lstk save pod: env: LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }} ... @@ -103,75 +103,41 @@ You can preserve your AWS infrastructure with Localstack in various ways. Find more information about cloud pods [here](/aws/developer-tools/snapshots/cloud-pods). -#### Ephemeral Instance (Preview) - -Our Github Action contains the prebuilt functionality to spin up an ephemeral instance. - -First you need to deploy the preview: - -```yaml showshowLineNumbers -name: Create PR Preview - -on: - pull_request: - types: [opened, synchronize, reopened] - -jobs: - test: - runs-on: ubuntu-latest - timeout-minutes: 15 - permissions: - pull-requests: write - steps: - ... - - - name: Deploy Preview - uses: LocalStack/setup-localstack@v0.2.2 - env: - AWS_DEFAULT_REGION: us-east-1 - AWS_REGION: us-east-1 - AWS_ACCESS_KEY_ID: test - AWS_SECRET_ACCESS_KEY: test - with: - state-backend: ephemeral - state-action: start - github-token: ${{ secrets.GITHUB_TOKEN }} - skip-ephemeral-stop: 'true' # We want our instance keep running - preview-cmd: bin/deploy.sh -``` - -Find out more about ephemeral instances [here](/aws/developer-tools/cloud-sandbox/ephemeral-instances). - #### Artifact +Instead of the LocalStack platform, you can keep the state as a local snapshot file and move it between runs with GitHub's own artifact storage. + ```yaml showshowLineNumbers ... -- name: Start LocalStack and Load State - uses: LocalStack/setup-localstack@v0.2.2 - continue-on-error: true # Allow it to fail as pod does not exist at first run +- name: Download the previous state + continue-on-error: true # Allow it to fail as the artifact does not exist at first run + uses: actions/download-artifact@v4 with: - install-awslocal: 'true' - state-backend: cloud-pods - state-action: load - state-name: my-ls-state + name: my-ls-state + +- name: Start LocalStack and load the state + run: | + lstk start + if [ -f ls-state.snapshot ]; then + lstk load ./ls-state.snapshot --merge=overwrite + fi env: LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }} ... -- name: Save LocalStack State - uses: LocalStack/setup-localstack@v0.2.2 +- name: Save the state + run: lstk save ./ls-state.snapshot + +- name: Upload the state + uses: actions/upload-artifact@v4 with: - install-awslocal: 'true' - state-backend: cloud-pods - state-action: save - state-name: my-ls-state - env: - LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }} + name: my-ls-state + path: ls-state.snapshot ... ``` -More information about state import and export [here](/aws/developer-tools/snapshots/export-import-state). +More information about [snapshots](/aws/developer-tools/snapshots/saving-snapshots-locally/). ## Current Limitations diff --git a/src/content/docs/aws/ci-pipelines/gitlab-ci.md b/src/content/docs/aws/ci-pipelines/gitlab-ci.md index 87a0dd3af..d4e60165a 100644 --- a/src/content/docs/aws/ci-pipelines/gitlab-ci.md +++ b/src/content/docs/aws/ci-pipelines/gitlab-ci.md @@ -3,14 +3,12 @@ title: GitLab CI description: Use LocalStack in GitLab CI. template: doc sidebar: - order: 5 + order: 6 --- -This page contains easily customisable snippets to show you how to manage LocalStack in a GitLab CI pipeline. +This page contains easily customizable snippets to show you how to manage LocalStack in a GitLab CI pipeline with the [`lstk` CLI](/aws/developer-tools/running-localstack/lstk/). -## Snippets - -### Start up Localstack +GitLab runs your job in one container and the Docker daemon in another, so every snippet below pairs the job with a Docker-in-Docker (`dind`) service. :::tip While working with a Docker-in-Docker (`dind`) setup, the Docker runner requires `privileged` mode. @@ -18,36 +16,24 @@ You must always use `privileged = true` in your GitLab CI's `config.toml` file w For more information, see [GitLab CI Docker-in-Docker](https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#use-docker-in-docker-executor) documentation. ::: +## Snippets -
-For LocalStack versions before 3.0.0 -Under test>variables, add:
-LOCALSTACK_HOSTNAME: localhost.localstack.cloud
-HOSTNAME_EXTERNAL: localhost.localstack.cloud. -
+### Start up LocalStack -#### Service +LocalStack requires a [CI Auth Token](https://app.localstack.cloud/workspace/auth-tokens), which you must add to the repository's environment variables as `LOCALSTACK_AUTH_TOKEN`. +Go to your project's **Settings > CI/CD** and expand the **Variables** section. +Select the **Add Variable** button and fill in the necessary details with `LOCALSTACK_AUTH_TOKEN` as the key and your CI Auth Token as the value. +After you create the variable, you can use it in the `.gitlab-ci.yml` file. -```yaml showshowLineNumbers -... -variables: - DOCKER_SOCK: tcp://docker:2375 - DOCKER_HOST: tcp://docker:2375 - DOCKER_TLS_CERTDIR: "" -... -services: - - name: localstack/localstack:latest - alias: localstack - - name: docker:dind - alias: docker - command: ["--tls=false"] -... -``` +However, variables set in the GitLab UI are not automatically passed down to service containers. +You need to assign them as variables in the UI, and then re-assign them in your `.gitlab-ci.yml`. #### Container +In this setup, `lstk` owns the emulator's lifecycle: `DOCKER_HOST` points it at the `dind` daemon, and `lstk start` runs the emulator container there. + ```yaml showshowLineNumbers -image: docker:latest +image: node:22 stages: - job @@ -55,11 +41,10 @@ stages: job: stage: job variables: - ... DOCKER_HOST: tcp://docker:2375 DOCKER_TLS_CERTDIR: "" - AWS_ENDPOINT_URL: "http://localhost.localstack.cloud:4566" - ... + LOCALSTACK_AUTH_TOKEN: $LOCALSTACK_AUTH_TOKEN + LOCALSTACK_HOST: localhost.localstack.cloud:4566 services: - name: docker:dind @@ -67,57 +52,95 @@ job: command: ["--tls=false"] before_script: - - apk update - - apk add gcc musl-dev linux-headers py3-pip python3 python3-dev - - python3 -m pip install localstack awscli - script: - - docker pull localstack/localstack:latest + - npm install -g @localstack/lstk + - apt-get update && apt-get install -y awscli - dind_ip="$(getent hosts docker | cut -d' ' -f1)" - - echo "${dind_ip} localhost.localstack.cloud " >> /etc/hosts - - DOCKER_HOST="tcp://${dind_ip}:2375" localstack start -d + - echo "${dind_ip} localhost.localstack.cloud" >> /etc/hosts + - lstk setup aws + script: + - lstk start + - lstk aws s3 mb s3://test-bucket + - lstk aws s3 ls ``` -### Configure a CI Auth Token +`lstk start` pulls the image, validates your license, and returns only once the emulator is ready, so no separate wait step is needed. +Because the emulator runs on the `dind` daemon, its ports are published on the `docker` service rather than on the job container. +The `/etc/hosts` entry and `LOCALSTACK_HOST` are what let `lstk` and your tests reach it at `localhost.localstack.cloud:4566`; without them `lstk` falls back to `127.0.0.1`, where nothing is listening. -You can easily enable LocalStack for AWS by using the `localstack/localstack-pro` image and adding your [CI Auth Token](https://app.localstack.cloud/workspace/auth-tokens) to the repository's environment variables as `LOCALSTACK_AUTH_TOKEN`. -Go to your project's **Settings > CI/CD** and expand the **Variables** section. -Select the **Add Variable** button and fill in the necessary details with `LOCALSTACK_AUTH_TOKEN` as the key and your CI Auth Token as the value. -After you create the variable, you can use it in the `.gitlab-ci.yml` file. +:::note +`lstk` bind-mounts the Docker socket into the emulator, and sets the emulator's own `DOCKER_HOST`, only when it reaches the daemon over a Unix socket. +A TCP `dind` daemon has no socket to mount, so services that spawn their own containers (Lambda, ECS, EKS) need the daemon address passed in explicitly. +`lstk start` forwards `LOCALSTACK_`-prefixed variables to the emulator, which strips the prefix, so set `LOCALSTACK_DOCKER_HOST` to the `dind` daemon as seen from inside the `dind` network (its bridge gateway, usually `tcp://172.17.0.1:2375`). +::: -However, variables set in the GitLab UI are not automatically passed down to service containers. -You need to assign them as variables in the UI, and then re-assign them in your `.gitlab-ci.yml`. +#### Service + +Alternatively, run LocalStack as a GitLab service container and use `lstk` purely as a client, pointing it at the service with `LSTK_ENDPOINT_URL`. +GitLab passes the job's `variables` to service containers too, so the emulator picks up both the auth token and the Docker connection directly, with no prefixing required. ```yaml showshowLineNumbers -... -variables: - LOCALSTACK_AUTH_TOKEN: $LOCALSTACK_AUTH_TOKEN -... -services: - - name: localstack/localstack-pro:latest - alias: localstack -... +image: node:22 + +stages: + - job + +job: + stage: job + variables: + DOCKER_SOCK: tcp://docker:2375 + DOCKER_HOST: tcp://docker:2375 + DOCKER_TLS_CERTDIR: "" + LOCALSTACK_AUTH_TOKEN: $LOCALSTACK_AUTH_TOKEN + LSTK_ENDPOINT_URL: http://localstack:4566 + + services: + - name: localstack/localstack-pro:latest + alias: localstack + - name: docker:dind + alias: docker + command: ["--tls=false"] + + before_script: + - npm install -g @localstack/lstk + - apt-get update && apt-get install -y awscli curl + - | + for _ in $(seq 1 60); do + curl -sf "${LSTK_ENDPOINT_URL}/_localstack/health" > /dev/null && break + sleep 2 + done + script: + - lstk aws s3 mb s3://test-bucket + - lstk aws s3 ls ``` -You can check the logs of the LocalStack container to see if the activation was successful. -If the CI Auth Token activation fails, LocalStack container will exit with an error code. +GitLab starts service containers before the job's first command, but does not wait for them to become ready, hence the health poll. -### Dump Localstack logs +### Dump LocalStack logs ```yaml showshowLineNumbers ... job: - variables: - LOCALSTACK_HOST: : script: - - localstack logs | tee localstack.log -... + - set +e + - ; status=$? + - lstk logs --verbose | tee localstack.log + - exit $status + artifacts: + when: always + paths: + - localstack.log +... ``` -In case of the service setup `LOCALSTACK_HOST` will be `localstack:4566`. +Collect the logs as the last `script` step rather than in `after_script`, where the emulator container is no longer reachable. +Capturing the test command's exit code keeps the job's result intact while still writing the logs after a failing test, which is when they matter most. + +In the [Service](#service) setup, `lstk logs` is not available, because `lstk` does not manage the service container. +Set `CI_DEBUG_SERVICES: "true"` to have GitLab stream the service container's logs into the job log instead. -### Store Localstack state +### Store LocalStack state -You can preserve your AWS infrastructure with Localstack in various ways. +You can preserve your AWS infrastructure with LocalStack in various ways. #### Artifact @@ -125,18 +148,18 @@ You can preserve your AWS infrastructure with Localstack in various ways. ... job: before_script: - - (test -f ./ls-state-pod.zip && localstack state import ./ls-state-pod.zip) || true + - (test -f ./ls-state.snapshot && lstk load ./ls-state.snapshot --merge=overwrite) || true script: ... - - localstack state export ./ls-state-pod.zip + - lstk save ./ls-state.snapshot ... artifacts: paths: - - $CI_PROJECT_DIR/ls-state-pod.zip + - $CI_PROJECT_DIR/ls-state.snapshot ... ``` -More info about Localstack's state export and import [here](/aws/developer-tools/snapshots/export-import-state/). +More info about LocalStack's snapshots [here](/aws/developer-tools/snapshots/saving-snapshots-locally/). #### Cache @@ -144,22 +167,22 @@ More info about Localstack's state export and import [here](/aws/developer-tools ... job: before_script: - - (test -f ./ls-state-pod.zip && localstack state import ./ls-state-pod.zip) || true + - (test -f ./ls-state.snapshot && lstk load ./ls-state.snapshot --merge=overwrite) || true script: ... - - localstack state export ./ls-state-pod.zip + - lstk save ./ls-state.snapshot ... cache: key: untracked: true files: - - $CI_PROJECT_DIR/ls-state-pod.zip + - $CI_PROJECT_DIR/ls-state.snapshot paths: - - $CI_PROJECT_DIR/ls-state-pod.zip + - $CI_PROJECT_DIR/ls-state.snapshot ... ``` -Additional information about state export and import [here](/aws/developer-tools/snapshots/export-import-state/). +Additional information about snapshots [here](/aws/developer-tools/snapshots/saving-snapshots-locally/). #### Cloud Pod @@ -167,58 +190,19 @@ Additional information about state export and import [here](/aws/developer-tools ... job: before_script: - - localstack pod load || true + - lstk load pod: || true script: ... - - localstack pod save -... -``` - -Find more information about cloud pods [here](/aws/developer-tools/snapshots/cloud-pods). - -#### Ephemeral Instance (Preview) - -```yaml showshowLineNumbers -... -variables: - LOCALSTACK_AUTH_TOKEN: $LOCALSTACK_AUTH_TOKEN -... -setup-job: - stage: build - before_script: - - | - response=$(curl -X POST -d '{"auto_load_pod": "false"}' \ - -H 'ls-api-key: $LOCALSTACK_API_KEY' \ - -H 'authorization: token $LOCALSTACK_API_KEY' \ - -H 'content-type: application/json' \ - https://api.localstack.cloud/v1/previews/my-gitlab-state) - - if [ "$endpointUrl" = "null" ] || [ "$endpointUrl" = "" ]; then - echo "Unable to create preview environment. API response: $response" - exit 1 - fi - echo "Created preview environment with endpoint URL: $endpointUrl" - - echo "export AWS_ENDPOINT_URL=$endpointUrl" - echo "$AWS_ENDPOINT_URL" >> ls-endpoint.env - ... - artifacts: - reports: - dotenv: ls-endpoint.env - -test-job: - stage: test - script: - - echo "$AWS_ENDPOINT_URL" # Output is the address of the ephemeral instance + - lstk save pod: ... ``` -Find out more about ephemeral instances [here](/aws/developer-tools/cloud-sandbox/ephemeral-instances). +Find more information about Cloud Pods [here](/aws/developer-tools/snapshots/cloud-pods). ## Current Limitations -- Localstack must be able to reach a docker socket to provision containers for certain services, ie Lambda, EKS, ECS...etc -- the runner must be able to resolve the Localstack domain (by default _localhost.localstack.cloud_), see the sample pipelines for a possible solution -- to be able to separate steps into their own jobs one must preserve Localstack's state, since Gitlab is not preserving job related containers/services during the pipelines -- to start up Localstack in Gitlab CI Docker tools are necessary -- when Localstack run as a container, it's not accessible during the `after_script` phase +- LocalStack must be able to reach a Docker socket to provision containers for certain services, such as Lambda, EKS, and ECS. +- The runner must be able to resolve the LocalStack domain (by default _localhost.localstack.cloud_); see the sample pipelines for a possible solution. +- To separate steps into their own jobs, you must preserve LocalStack's state, since GitLab does not preserve job-related containers or services across a pipeline. +- Docker tooling is necessary to start up LocalStack in GitLab CI. +- When LocalStack runs as a container, it is not accessible during the `after_script` phase. diff --git a/src/content/docs/aws/ci-pipelines/index.md b/src/content/docs/aws/ci-pipelines/index.md deleted file mode 100644 index 49b8ee068..000000000 --- a/src/content/docs/aws/ci-pipelines/index.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Overview -description: Use LocalStack in your CI environment to run tests against your AWS infrastructure in a high-fidelity cloud emulator. -template: doc -sidebar: - order: 1 ---- - -LocalStack makes it easy to integrate cloud-native testing into your CI pipelines, without the complexity of managing real AWS environments. Running fully local AWS emulation inside your CI jobs lets you automate application testing, catch issues earlier, and ship with confidence. - -LocalStack supports: - -- Native integration with platforms like CircleCI -- A generic CI driver for other CI/CD systems -- Advanced features like Cloud Pods to track performance and test coverage - -With LocalStack in your CI pipeline, you can eliminate slow and costly staging environments while ensuring realistic, high-fidelity cloud testing before deploying to production. - -## Hypothetical CI workflow - -Let's assume that your team has an automated CI workflow into which you want to integrate end-to-end cloud testing with LocalStack. -As an example, consider the following pipeline, which represents part of a simple CI workflow: - -![An example CI/CD workflow using LocalStack](/images/aws/localstack-in-ci.svg) - -The CI build is triggered by pushing code to a version control repository, like GitHub. -The CI runner starts LocalStack and executes the test suite. -You can also use the same Infrastructure-as-Code (IaC) configuration that you use to set up AWS in your production environment to set up LocalStack in the CI environment. -You can also pre-seed state into the local AWS services (e.g., DynamoDB entries or S3 files) provided by LocalStack in your CI environment via [Cloud Pods](/aws/developer-tools/snapshots/cloud-pods). - -After a successful test run, you can execute the more expensive AWS CodeBuild pipeline for deploying your application. -You can enrich the test reports created by your testing framework with traces and analytics generated inside LocalStack. - -## CI images - -LocalStack CI images require a [CI Auth Token](https://app.localstack.cloud/workspace/auth-tokens) for deployment within your CI environment. - -We exclusively support the [`localstack/localstack` image in Docker Hub](https://hub.docker.com/r/localstack/localstack) for all CI implementations. Detailed configuration and image specifications are available on our [Docker images](https://docs.localstack.cloud/references/docker-images/) documentation. - -:::note -**Auth Token Requirement**: Using LocalStack in a CI environment requires a valid Auth Token. Ensure your environment variables are configured to include your token to avoid authentication failures during image pull or container initialization. -::: - -LocalStack Docker images can be used in your CI environment by adding an [Auth Token](https://docs.localstack.cloud/aws/getting-started/auth-token/). - -The LocalStack Docker image is available on [Docker Hub](https://hub.docker.com/r/localstack/localstack/tags), and here is our [Docker images documentation](https://docs.localstack.cloud/references/docker-images/). - - -## CI integrations - -The steps required for the integration differ slightly depending on your preferred CI provider. -Please refer to the relevant documentation below to configure LocalStack for your CI pipelines. diff --git a/src/content/docs/aws/ci-pipelines/index.mdx b/src/content/docs/aws/ci-pipelines/index.mdx new file mode 100644 index 000000000..ace718940 --- /dev/null +++ b/src/content/docs/aws/ci-pipelines/index.mdx @@ -0,0 +1,55 @@ +--- +title: Overview +description: Use LocalStack in your CI environment to run tests against your AWS infrastructure in a high-fidelity cloud emulator. +template: doc +sidebar: + order: 1 +--- + +import SectionCards from '../../../../components/SectionCards.astro'; + +Running integration tests against real AWS in CI means maintaining cloud accounts, waiting on slow provisioning, and sharing a staging environment with every other pipeline. +LocalStack replaces all of that with an emulator that runs inside the CI job itself. +Deploy with the same Infrastructure as Code you already use in production, run your test suite against emulated AWS APIs, and discard the environment when the job ends. +Every run gets a fresh emulator instance, and no test ever requires a real AWS account. + +## CI workflow overview + +The following diagram illustrates a typical CI workflow, using LocalStack instead of the AWS cloud: + +![An example CI/CD workflow using LocalStack](/images/aws/localstack-in-ci.svg) + +A CI build is triggered when you push source code to your version control repository (such as GitHub). +The CI runner checks out the source code, then runs a sequence of build and test steps. +Where those tests depend on AWS services, they run against the LocalStack emulator rather than the real AWS cloud. +You create the resources they need with standard tools such as Terraform, or load them from a [Cloud Pod](/aws/developer-tools/snapshots/cloud-pods/) to avoid redeploying your infrastructure on every run. + +If the tests pass, your CD pipeline takes over and deploys the application to real AWS infrastructure. +A deployment therefore only ever starts from a build that has already been validated against emulated AWS, which increases your confidence in the code you ship. + +## CI integrations + +The steps required to run LocalStack in CI are largely the same, no matter which CI provider you use (such as GitHub Actions, GitLab CI, or CircleCI): + +1. Expose a CI Auth Token +2. Install the `lstk` CLI and related tools +3. Start the emulator +4. Seed the emulator with the resources you need +5. Run your tests +6. Collect the output logs + +Start with the [CI Best Practices](/aws/ci-pipelines/best-practices/) page for the commands behind each step, then select your CI provider below for its own syntax and features. + + diff --git a/src/content/docs/aws/ci-pipelines/travis-ci.md b/src/content/docs/aws/ci-pipelines/travis-ci.md index 05905869c..ac1567e54 100644 --- a/src/content/docs/aws/ci-pipelines/travis-ci.md +++ b/src/content/docs/aws/ci-pipelines/travis-ci.md @@ -3,69 +3,55 @@ title: Travis CI description: Use LocalStack in Travis CI. template: doc sidebar: - order: 7 + order: 8 --- -This guide shows how to start and use LocalStack in your Travis CI jobs. +This guide shows how to start and use LocalStack in your Travis CI jobs, managed with the [`lstk` CLI](/aws/developer-tools/running-localstack/lstk/). + +## Configuring a CI Auth Token + +`lstk` validates your LocalStack license before it starts the emulator, so a [CI Auth Token](https://app.localstack.cloud/workspace/auth-tokens) is required rather than a personal Developer Auth Token. + +To configure this in Travis CI, go to the project settings (`More options` → `Settings`), scroll down to the `Environment Variables` section, and add your CI Auth Token as `LOCALSTACK_AUTH_TOKEN`. +Travis CI exposes the variable to the build, and `lstk` picks it up from the environment and passes it to the emulator container. +Keep `Display value in build log` switched off so the token is not printed. ## Setting up the Travis CI job When you want to integrate LocalStack into your job configuration, you just have to execute the following steps: -- Install the LocalStack CLI (and maybe also `awslocal`). -- Make sure your LocalStack docker image is up-to-date by pulling the latest version. -- Use the LocalStack CLI to start LocalStack. - Make sure to use the `-d` flag to start the LocalStack docker container in detached mode. -- Wait for the container to report that it is up and running. +- Install `lstk`, along with the AWS CLI that `lstk aws` proxies. +- Generate the `localstack` AWS profile with `lstk setup aws`. +- Use `lstk` to start LocalStack. + +There is no need to pull the image or wait for the container: `lstk start` pulls the image if needed and returns only once the emulator is ready. The following example Travis CI job config (`.travis.yaml`) executes these steps, creates a new S3 bucket, and prints a nice message in the end: ```yaml showshowLineNumbers -language: python +language: node_js + +node_js: + - "22" services: - docker -python: - - "3.8" - before_install: - # Install the LocalStack CLI and awslocal - - python -m pip install localstack awscli-local[ver1] - # Make sure to pull the latest version of the image - - docker pull localstack/localstack - # Start LocalStack in the background - - localstack start -d - # Wait 30 seconds for the LocalStack container to become ready before timing out - - echo "Waiting for LocalStack startup..." - - localstack wait -t 30 - - echo "Startup complete" + # Install lstk + - npm install -g @localstack/lstk + # Install the AWS CLI, which `lstk aws` runs under the hood + - curl -sSL "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip + - unzip -q awscliv2.zip && sudo ./aws/install + # Write the localstack AWS profile, so lstk does not warn that it's missing + - lstk setup aws + # Start LocalStack; LOCALSTACK_AUTH_TOKEN comes from the project's environment variables + - lstk start script: # Test LocalStack by creating a new S3 bucket (and verify that it has been created by listing all buckets) - - awslocal s3 mb s3://test - - awslocal s3 ls + - lstk aws s3 mb s3://test + - lstk aws s3 ls - echo "Execute your tests here :)" ``` -## Configuring a CI Auth Token - -You can easily enable LocalStack for AWS by using the `localstack/localstack-pro` image and adding your [CI Auth Token](https://app.localstack.cloud/workspace/auth-tokens) to the project's environment variables as `LOCALSTACK_AUTH_TOKEN`. -The LocalStack CLI will automatically detect it and activate the Pro features. - -To configure this in Travis CI, go to the project settings (`More options` → `Settings`), scroll down to the `Environment Variables` section, and add your CI Auth Token as `LOCALSTACK_AUTH_TOKEN`. - -Here is an example workflow: - -```yaml showshowLineNumbers -before_install: - # Install the LocalStack CLI and awslocal - - python -m pip install localstack awscli-local[ver1] - # Make sure to pull the latest version of the image - - docker pull localstack/localstack-pro - # Start LocalStack in the background - - localstack start -d - # Wait 30 seconds for the LocalStack container to become ready before timing out - - echo "Waiting for LocalStack startup..." - - localstack wait -t 30 - - echo "Startup complete" -``` \ No newline at end of file +Travis CI images vary by language and distribution, so drop either install step if your image already provides the tool. diff --git a/src/content/docs/aws/connecting/aws-cli.md b/src/content/docs/aws/connecting/aws-cli.md index 3156cbe72..1ccf4161f 100644 --- a/src/content/docs/aws/connecting/aws-cli.md +++ b/src/content/docs/aws/connecting/aws-cli.md @@ -8,31 +8,31 @@ sidebar: ## Introduction -The [AWS Command Line Interface (CLI)](https://aws.amazon.com/cli/) is a unified tool for creating and managing AWS services via a command line interface. -All CLI commands applicable to services implemented within [LocalStack](/aws/connecting/aws-cli/) can be executed when operating against LocalStack. +The [AWS Command Line Interface (CLI)](https://aws.amazon.com/cli/) is the standard tool from Amazon for creating and managing AWS services via a command line interface. +Due to LocalStack's compatibility with the AWS APIs, this tool can also access LocalStack's emulated services. -You can use the AWS CLI with LocalStack using either of the following approaches: +You can use the AWS CLI with LocalStack using one or more of the following approaches: -[AWS CLI](#aws-cli) +- [AWS CLI](#aws-cli) - Use the standard `aws` command with hand-crafted configuration options necessary to communicate with LocalStack. +- [LocalStack AWS CLI](#localstack-aws-cli-lstk-aws) - Use the `lstk aws` command to set the configuration options for you. +- [Using AWS CLI from a pre-built container](#using-aws-cli-from-a-pre-built-container) - Use Amazon's pre-built AWS CLI container image instead of installing `aws` locally. -[LocalStack AWS CLI](#localstack-aws-cli-awslocal) +:::note +`lstk aws` supersedes the older [`awslocal` wrapper script](/aws/connecting/infrastructure-as-code/deprecated-wrapper-scripts#awslocal), which is deprecated but still available if you need it. +::: ## AWS CLI -You can install `aws` by using the following command if it's not already installed. - -```bash -pip install awscli -``` +If you don't already have `aws` (version 2) installed, follow the [official AWS CLI installation instructions](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). -You can configure the AWS CLI to redirect AWS API requests to LocalStack using two approaches: +Once installed, you can configure the AWS CLI to redirect AWS API requests to LocalStack using two approaches: - [Configuring an endpoint URL](#configuring-an-endpoint-url) - [Configuring a custom profile](#configuring-a-custom-profile) ### Configuring an endpoint URL -You can use AWS CLI with an endpoint URL by configuring test environment variables and include the `--endpoint-url=` flag in your `aws` CLI commands. +You can use AWS CLI with an endpoint URL by configuring environment variables and including the `--endpoint-url=` flag in your `aws` CLI commands. For example: ```bash @@ -80,86 +80,32 @@ aws s3 ls --profile localstack Alternatively, you can also set the `AWS_PROFILE=localstack` environment variable, in which case the `--profile localstack` parameter can be omitted in the commands above. ::: -## LocalStack AWS CLI (`awslocal`) +## LocalStack AWS CLI (`lstk aws`) -`awslocal` serves as a thin wrapper and a substitute for the standard `aws` command, enabling you to run AWS CLI commands within the LocalStack environment without specifying the `--endpoint-url` parameter or a profile. +`lstk aws` serves as a thin wrapper and a substitute for the standard `aws` command, enabling you to run AWS CLI commands within the LocalStack environment without specifying the `--endpoint-url` parameter or a profile. ### Installation -Install the `awslocal` command using the following command: - -```bash -pip install awscli-local[ver1] -``` +To make use of `lstk aws`, you must install both the `lstk` CLI and the standard `aws` command from Amazon. -:::tip - -The above command installs the most recent version of the underlying AWS CLI version 1 (`awscli`) package. -If you would rather manage your own `awscli` version (e.g., `v1` or `v2`) and only install the wrapper script, you can use the following command: - -```bash -pip install awscli-local -``` - -::: - -:::note - -Automatic installation of AWS CLI version 2 is currently not supported yet (at the time of writing there is no official pypi package for `v2` available), but the `awslocal` technically also works with AWS CLI v2 (see [this section](#current-limitations) for more details). -::: +1. To install `lstk`, follow the [`lstk` installation instructions](/aws/developer-tools/running-localstack/lstk/#installation). +2. To install `aws`, follow the [official AWS CLI installation instructions](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). ### Usage -The `awslocal` command shares identical usage with the standard `aws` command. -For comprehensive usage instructions, refer to the manual pages by running `awslocal help`. - -```bash -awslocal kinesis list-streams -``` - -### Configuration - -| Variable Name | Description | -| ---------------- | ----------------------------------------------------------------------------------- | -| AWS_ENDPOINT_URL | The endpoint URL to connect to (takes precedence over USE_SSL/LOCALSTACK_HOST) | -| LOCALSTACK_HOST | (deprecated) A variable defining where to find LocalStack (default: localhost:4566) | -| USE_SSL | (deprecated) Whether to use SSL when connecting to LocalStack (default: False) | - -### Current Limitations - -Please note that there is a known limitation for using the `cloudformation package ...` command with the AWS CLI v2. -The problem is that the AWS CLI v2 is [not available as a package on pypi.org](https://github.com/aws/aws-cli/issues/4947), but is instead shipped as a binary package that cannot be easily patched from `awslocal`. -To work around this issue, you have 2 options: - -- Downgrade to the v1 AWS CLI (this is the recommended approach) -- There is an unofficial way to install AWS CLI v2 from sources. - We do not recommend this, but it is technically possible. - Also, you should install these libraries in a Python virtualenv, to avoid version clashes with other libraries on your system: +The `lstk aws` command shares identical usage with the standard `aws` command. +For comprehensive usage instructions, refer to the manual pages by running `lstk aws help`. ```bash -virtualenv .venv -. .venv/bin/activate -pip install https://github.com/boto/botocore/archive/v2.zip https://github.com/aws/aws-cli/archive/v2.zip +lstk aws kinesis list-streams ``` -Please also note there is a known limitation for issuing requests using -`--no-sign-request` with the AWS CLI. -LocalStack's routing mechanism depends on -the signature of each request to identify the correct service for the request. -Thus, adding the flag `--no-sign-requests` provokes your request to reach the -wrong service. -One possible way to address this is to use the `awslocal` CLI -instead of AWS CLI. - -## AWS CLI v2 - -Automatic installation of AWS CLI version 2 is currently not supported (at the time of writing there is no official pypi package for v2 available), but the awslocal technically also works with AWS CLI v2 (see this section for more details). -### AWS CLI v2 with Docker and LocalStack +## Using AWS CLI from a pre-built container -By default, the container running [amazon/aws-cli](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-docker.html) is isolated from `0.0.0.0:4566` on the host machine, that means that aws-cli cannot reach localstack through your shell. +As an alternative to installing the `aws` command directly on your local machine, Amazon provides a [pre-built container image with the AWS CLI pre-installed](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-docker.html). This approach is most suitable when working in multi-container environments, rather than single-machine installations. If you take this approach, an extra step is required for communication with LocalStack, also running inside a container. -To ensure that the two docker containers can communicate create a network on the docker engine: +By default, the AWS CLI container is isolated from `0.0.0.0:4566` on the host machine, which means the AWS CLI cannot reach LocalStack. To ensure the two docker containers can communicate create a network on the docker engine: ```bash docker network create localstack @@ -175,7 +121,7 @@ networks: name: 'localstack' ``` -Run AWS Cli v2 docker container using this network (example): +Run the AWS CLI v2 docker container using this network (example): ```bash docker run --network localstack --rm -it amazon/aws-cli --endpoint-url=http://localstack:4566 lambda list-functions diff --git a/src/content/docs/aws/connecting/infrastructure-as-code/aws-cdk.md b/src/content/docs/aws/connecting/infrastructure-as-code/aws-cdk.md index 73737094d..48e103a2f 100644 --- a/src/content/docs/aws/connecting/infrastructure-as-code/aws-cdk.md +++ b/src/content/docs/aws/connecting/infrastructure-as-code/aws-cdk.md @@ -14,40 +14,43 @@ The AWS Cloud Development Kit (CDK) is an Infrastructure-as-Code (IaC) tool usin ## AWS CDK CLI for LocalStack -`cdklocal` is a thin wrapper script for using the [AWS CDK](https://github.com/aws/aws-cdk) library against local APIs provided by LocalStack. +[`lstk cdk`](/aws/developer-tools/running-localstack/lstk/#cdk) proxies the [AWS CDK](https://github.com/aws/aws-cdk) library against local APIs provided by LocalStack. It requires the AWS CDK CLI version `2.177.0` or newer on your `PATH`. + +:::note +`lstk cdk` supersedes the older [`cdklocal` wrapper script](/aws/connecting/infrastructure-as-code/deprecated-wrapper-scripts#cdklocal), which is deprecated but still available if you need it. +::: ### Installation -The `cdklocal` command line is published as an [npm library](https://www.npmjs.com/package/aws-cdk-local): +Install `lstk` by following the [`lstk` installation instructions](/aws/developer-tools/running-localstack/lstk/#installation). +You'll also need the AWS CDK CLI installed separately: ```bash # Install globally -npm install -g aws-cdk-local aws-cdk +npm install -g aws-cdk # Verify it installed correctly -cdklocal --version -# e.g. 1.65.5 +cdk --version ``` -:::note - -Using `cdklocal` locally (e.g. within the `node_modules` of your repo instead of globally installed) does not work at the moment for some setups, so make sure you install both `aws-cdk` and `aws-cdk-local` with the `-G` flag. -::: - ### Usage -`cdklocal` can be used as a drop-in replacement of where you would otherwise use `cdk` when targeting the AWS Cloud. +`lstk cdk` can be used as a drop-in replacement of where you would otherwise use `cdk` when targeting the AWS Cloud. ```bash -cdklocal --help +lstk cdk --help ``` ### Configuration +`lstk cdk`'s only lstk-specific flag (before the CDK action) is `--region ` (default `us-east-1`); CDK always targets the default LocalStack account `000000000000`, so there is no `--account` flag. + The following environment variables can be configured: - `AWS_ENDPOINT_URL`: The endpoint URL (i.e., protocol, host, and port) to connect to LocalStack (default: `http://localhost.localstack.cloud:4566`) -- `LAMBDA_MOUNT_CODE`: Whether to use local Lambda code mounting (via setting `hot-reload` S3 bucket name) +- `AWS_ENDPOINT_URL_S3`: The S3-specific endpoint URL, required alongside `AWS_ENDPOINT_URL` and must include `.s3.` to correctly identify S3 API calls +- `LSTK_CDK_CMD`: Binary to invoke (default `cdk`) +- `AWS_REGION`: Fallback for `--region` ### Example @@ -62,20 +65,20 @@ The CDK command line ships with a sample app generator to run a quick test for g ```bash # create sample app mkdir /tmp/test; cd /tmp/test -cdklocal init sample-app --language=javascript +lstk cdk init sample-app --language=javascript # bootstrap localstack environment -cdklocal bootstrap +lstk cdk bootstrap # deploy the sample app -cdklocal deploy +lstk cdk deploy > Do you wish to deploy these changes (y/n)? y ``` -Once the deployment is done, you can inspect the created resources via the [`awslocal`](https://github.com/localstack/awscli-local) command line +Once the deployment is done, you can inspect the created resources via the [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command line ```bash -awslocal sns list-topics +lstk aws sns list-topics { "Topics": [ { @@ -107,21 +110,5 @@ When this lambda is executed locally from the `/tmp` folder, the package can not ## CDK Version Compatibility -`cdklocal` works with all installed versions of the Node.js `aws-cdk` package. -However, issues exist for `aws-cdk >= 2.177.0`. - -For these versions: - -- We unset AWS-related environment variables like `AWS_PROFILE` before calling `cdk`. -- We explicitly set `AWS_ENDPOINT_URL` and `AWS_ENDPOINT_URL_S3` to point to LocalStack. - -Some environment variables may cause conflicting config, such as wrong region or accidental deploys to real AWS. -To allow specific variables (e.g., `AWS_REGION`), use `AWS_ENVAR_ALLOWLIST`: - -```bash -AWS_ENVAR_ALLOWLIST=AWS_REGION,AWS_DEFAULT_REGION AWS_DEFAULT_REGION=eu-central-1 AWS_REGION=eu-central-1 cdklocal ... -``` - -If you manually set `AWS_ENDPOINT_URL`, it will be used. -You must also set `AWS_ENDPOINT_URL_S3`, and it must include `.s3.` to correctly identify S3 API calls. -See full configuration details [on our configuration docs](https://github.com/localstack/aws-cdk-local?tab=readme-ov-file#configurations). +`lstk cdk` requires AWS CDK CLI `2.177.0` or newer, as noted in [Installation](#installation). +If you're using an older `aws-cdk` version, or the legacy `cdklocal` wrapper script, see [CDK Version Compatibility](/aws/connecting/infrastructure-as-code/deprecated-wrapper-scripts#cdklocal) on the deprecated wrapper scripts page for the relevant environment-variable workarounds. diff --git a/src/content/docs/aws/connecting/infrastructure-as-code/aws-chalice.mdx b/src/content/docs/aws/connecting/infrastructure-as-code/aws-chalice.mdx index a91ea389c..a4e8ed7f3 100644 --- a/src/content/docs/aws/connecting/infrastructure-as-code/aws-chalice.mdx +++ b/src/content/docs/aws/connecting/infrastructure-as-code/aws-chalice.mdx @@ -20,7 +20,7 @@ Using LocalStack, you can kick-start your development process, create a new Chal Start LocalStack inside a Docker container by running: ```bash -localstack start -d +lstk start ``` Install the `chalice-local` package by running: diff --git a/src/content/docs/aws/connecting/infrastructure-as-code/aws-sam.md b/src/content/docs/aws/connecting/infrastructure-as-code/aws-sam.md index acf77ba04..5b3807862 100644 --- a/src/content/docs/aws/connecting/infrastructure-as-code/aws-sam.md +++ b/src/content/docs/aws/connecting/infrastructure-as-code/aws-sam.md @@ -12,29 +12,29 @@ The AWS Serverless Application Model (SAM) is an open-source framework for devel It uses a simplified syntax to define functions, APIs, databases, and event source mappings. When you deploy, SAM converts its syntax into AWS CloudFormation syntax, helping you create serverless applications more quickly. -LocalStack can work with SAM using the AWS SAM CLI for LocalStack. -This CLI comes in the form of a `samlocal` wrapper script, which lets you deploy SAM applications on LocalStack. -This guide explains how to set up local AWS resources using the `samlocal` wrapper script. +LocalStack can work with SAM using [`lstk sam`](/aws/developer-tools/running-localstack/lstk/#sam), which lets you deploy SAM applications on LocalStack. +This guide explains how to set up local AWS resources using `lstk sam`. -## `samlocal` wrapper script +## `lstk sam` -`samlocal` is a wrapper for the `sam` command line interface, facilitating the use of SAM framework with LocalStack. -When executing deployment commands like `samlocal ["build", "deploy", "validate", "package"]`, the script configures the SAM settings for LocalStack and runs the specified SAM command. +`lstk sam` proxies the `sam` command line interface, facilitating the use of the SAM framework with LocalStack. +When executing deployment commands like `lstk sam [ build | deploy | validate | package ]`, it configures the SAM settings for LocalStack and runs the specified SAM command. -### Install the `samlocal` wrapper script +:::note +`lstk sam` supersedes the older [`samlocal` wrapper script](/aws/connecting/infrastructure-as-code/deprecated-wrapper-scripts#samlocal), which is deprecated but still available if you need it. +::: -You can install the `samlocal` wrapper script by running the following command: +### Install lstk -```bash -pip install aws-sam-cli-local -``` +To use `lstk sam`, install `lstk` by following the [`lstk` installation instructions](/aws/developer-tools/running-localstack/lstk/#installation). +You'll also need the [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) (version `1.95.0` or newer) installed and on your `PATH`. ### Create a new SAM project You can initialize a new SAM project using the following command: ```bash -samlocal init +lstk sam init ``` Select `1` to create a new SAM application using an AWS Quick Start template. @@ -50,19 +50,29 @@ Then, enter the project name and press `Enter`. After initializing the SAM project, enter the project directory and deploy the application using the following command: ```bash -samlocal deploy --guided +lstk sam deploy --guided ``` Enter the default values for the deployment, such as the stack name, region, and confirm the changes. -The `samlocal` wrapper will package and deploy the application to LocalStack. +`lstk sam` will package and deploy the application to LocalStack. ### Configuration -| Environment Variable | Default value | Description | -|------------------------|--------------------------------------------------|-------------------------------------------------------------------------| -| AWS_ENDPOINT_URL | `http://localhost.localstack.cloud:4566` | URL at which the `boto3` client can reach LocalStack | -| EDGE_PORT (Deprecated) | `4566` | Port number under which the LocalStack edge service is available | -| LOCALSTACK_HOSTNAME (Deprecated) | `localhost` | Host under which the LocalStack edge service is available +The `lstk sam` command supports several options and environment variables beyond what is available with the standard `sam` command. +| Option | Default | Description | +|----------------------|-----------------|--------------| +| `--region ` | `us-east-1` | Deployment region | +| `--account ` | `000000000000` | Target AWS account id (12 digits) | + +`lstk sam`-specific flags must appear **before** the SAM action (for example, `lstk sam --region us-west-2 build`) + +| Environment Variable | Default value | Description | +|-------------------------|----------------|--------------| +| `AWS_ENDPOINT_URL` | - | Override the auto-resolved LocalStack endpoint | +| `AWS_ENDPOINT_URL_S3` | - | Override the auto-resolved LocalStack S3 endpoint | +| `LSTK_SAM_CMD` | `sam` | Binary to invoke | +| `AWS_REGION` | - | Fallback for `--region` | +| `AWS_ACCESS_KEY_ID` | - | Fallback for `--account` | ## Debugging on VS Code diff --git a/src/content/docs/aws/connecting/infrastructure-as-code/cloud-custodian.md b/src/content/docs/aws/connecting/infrastructure-as-code/cloud-custodian.md index 8d7f66337..cdff1fb88 100644 --- a/src/content/docs/aws/connecting/infrastructure-as-code/cloud-custodian.md +++ b/src/content/docs/aws/connecting/infrastructure-as-code/cloud-custodian.md @@ -16,7 +16,7 @@ You can use Cloud Custodian with LocalStack by just specifying the Cloud Custodi ## Getting started -This guide is designed for users who are new to Cloud Custodian and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users who are new to Cloud Custodian and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how you can spin up an EC2 instance and tag it with the key `Custodian`, and then use Cloud Custodian to stop the instance. @@ -33,12 +33,12 @@ After installing Cloud Custodian, you can configure a [custom LocalStack profile ### Create an EC2 instance -You can create an EC2 instance using the `awslocal` wrapper script. +You can create an EC2 instance using `lstk aws`. You can use the [`RunInstances`](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) API to create an EC2 instance. The following example creates an EC2 instance with the tag `Custodian` (any value): ```bash -awslocal ec2 run-instances \ +lstk aws ec2 run-instances \ --image-id ami-ff0fea8310f3 \ --count 1 \ --instance-type t3.nano \ diff --git a/src/content/docs/aws/connecting/infrastructure-as-code/crossplane.md b/src/content/docs/aws/connecting/infrastructure-as-code/crossplane.md index 08f8477cb..42b1c1f41 100644 --- a/src/content/docs/aws/connecting/infrastructure-as-code/crossplane.md +++ b/src/content/docs/aws/connecting/infrastructure-as-code/crossplane.md @@ -194,10 +194,10 @@ crossplane-test-bucket True True crossplane-test-bucket 30s ``` ... -and the bucket it should also be visible when querying the local S3 buckets in LocalStack via [`awslocal`](https://github.com/localstack/awscli-local): +and the bucket it should also be visible when querying the local S3 buckets in LocalStack via [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws): ```bash -awslocal s3 ls +lstk aws s3 ls ``` ```bash title="Output" @@ -233,7 +233,7 @@ crossplane-test-queue True True http://host.docker.internal:4566/000000 ...and the queue should be visible when listing the SQS queues in LocalStack: ```bash -awslocal sqs list-queues +lstk aws sqs list-queues ``` ```bash title="Output" diff --git a/src/content/docs/aws/connecting/infrastructure-as-code/deprecated-wrapper-scripts.md b/src/content/docs/aws/connecting/infrastructure-as-code/deprecated-wrapper-scripts.md new file mode 100644 index 000000000..9f89dde51 --- /dev/null +++ b/src/content/docs/aws/connecting/infrastructure-as-code/deprecated-wrapper-scripts.md @@ -0,0 +1,251 @@ +--- +title: Deprecated Wrapper Scripts +description: Reference for the legacy awslocal, tflocal, samlocal, and cdklocal wrapper scripts, superseded by lstk. +template: doc +sidebar: + order: 12 +--- + +## Introduction + +The following (now deprecated) wrapper scripts were used in conjunction with LocalStack, to direct the `aws`, `terraform`, `sam`, and `cdk` commands to LocalStack endpoints. + +- [`awslocal`](#awslocal) - Runs AWS CLI commands against LocalStack. +- [`tflocal`](#tflocal) - Runs Terraform against LocalStack. +- [`samlocal`](#samlocal) - Runs AWS SAM CLI commands against LocalStack. +- [`cdklocal`](#cdklocal) - Runs AWS CDK commands against LocalStack. + +:::caution +`awslocal`, `tflocal`, `samlocal`, and `cdklocal` are **deprecated** in favor of [`lstk`](/aws/developer-tools/running-localstack/lstk/), which provides equivalent functionality via `lstk aws`, `lstk terraform` (alias `lstk tf`), `lstk sam`, and `lstk cdk`. +These wrapper scripts remain available and continue to work. This page documents them for anyone still relying on them. +::: + +See the [AWS CLI](/aws/connecting/aws-cli), [Terraform](/aws/connecting/infrastructure-as-code/terraform), [AWS SAM](/aws/connecting/infrastructure-as-code/aws-sam), and [AWS CDK](/aws/connecting/infrastructure-as-code/aws-cdk) pages for the current `lstk`-based workflow. + + +## awslocal + +`awslocal` serves as a thin wrapper and a substitute for the standard `aws` command, enabling you to run AWS CLI commands within the LocalStack environment without specifying the `--endpoint-url` parameter or a profile. + +### Installation + +Install the `awslocal` command using the following command: + +```bash +pip install awscli-local[ver1] +``` + +:::tip +The above command installs the most recent version of the underlying AWS CLI version 1 (`awscli`) package. +If you would rather manage your own `awscli` version (e.g., `v1` or `v2`) and only install the wrapper script, you can use the following command: + +```bash +pip install awscli-local +``` + +::: + +:::note +Automatic installation of AWS CLI version 2 is not supported (at the time of writing there is no official pypi package for `v2` available), but the `awslocal` technically also works with AWS CLI v2 (see [Current Limitations](#current-limitations) for more details). +::: + +### Usage + +The `awslocal` command shares identical usage with the standard `aws` command. +For comprehensive usage instructions, refer to the manual pages by running `awslocal help`. + +```bash +awslocal kinesis list-streams +``` + +### Configuration + +| Variable Name | Description | +| ---------------- | ----------------------------------------------------------------------------------- | +| AWS_ENDPOINT_URL | The endpoint URL to connect to (takes precedence over USE_SSL/LOCALSTACK_HOST) | +| LOCALSTACK_HOST | A variable defining where to find LocalStack (default: `localhost:4566`) | +| USE_SSL | Whether to use SSL when connecting to LocalStack (default: False) | + +### Current Limitations + +Please note that there is a known limitation for using the `cloudformation package ...` command with the AWS CLI v2. +The problem is that the AWS CLI v2 is [not available as a package on pypi.org](https://github.com/aws/aws-cli/issues/4947), but is instead shipped as a binary package that cannot be easily patched from `awslocal`. +To work around this issue, you have 2 options: + +- Downgrade to the v1 AWS CLI (this is the recommended approach) +- There is an unofficial way to install AWS CLI v2 from sources. + We do not recommend this, but it is technically possible. + Also, you should install these libraries in a Python virtualenv, to avoid version clashes with other libraries on your system: + +```bash +virtualenv .venv +. .venv/bin/activate +pip install https://github.com/boto/botocore/archive/v2.zip https://github.com/aws/aws-cli/archive/v2.zip +``` + +Please also note there is a known limitation for issuing requests using +`--no-sign-request` with the AWS CLI. +LocalStack's routing mechanism depends on +the signature of each request to identify the correct service for the request. +Thus, adding the flag `--no-sign-requests` provokes your request to reach the +wrong service. +One possible way to address this is to use the `awslocal` CLI +instead of AWS CLI. + +## tflocal + +`tflocal` is a small wrapper script to run Terraform against LocalStack. It uses the [Terraform Override mechanism](https://www.terraform.io/language/files/override) and creates a temporary file `localstack_providers_override.tf` to configure the endpoints for the AWS `provider` section. +The endpoints for all services are configured to point to the LocalStack API (`http://localhost:4566` by default). + +### Installation + +To install the `tflocal` command, you can use `pip` (assuming you have a local Python installation): + +```bash +pip install terraform-local +``` + +After installation, you can use the `tflocal` command, which has the same interface as the `terraform` command line. + +```bash +tflocal --help +``` + +### Usage + +```bash +tflocal init +tflocal apply +``` + +### Configuration + +| Environment Variable | Default value | Description | +| ------------------------ | -------------------------------- | ----------- | +| `TF_CMD` | `terraform` | Terraform command to call | +| `AWS_ENDPOINT_URL` | - | Hostname and port of the target LocalStack instance | +| `LOCALSTACK_HOSTNAME` | `localhost` | Host name of the target LocalStack instance | +| `EDGE_PORT` | `4566` | Port number of the target LocalStack instance | +| `S3_HOSTNAME` | `s3.localhost.localstack.cloud` | Special hostname to be used to connect to LocalStack S3 | +| `USE_EXEC` | - | Whether to use `os.exec` instead of `subprocess.Popen` (try using this in case of I/O issues) | +| `_ENDPOINT` | - | Setting a custom service endpoint, e.g., `COGNITO_IDP_ENDPOINT=http://example.com` | +| `AWS_DEFAULT_REGION` | `us-east-1` | The AWS region to use (determined from local credentials if `boto3` is installed) | +| `CUSTOMIZE_ACCESS_KEY` | - | Enables you to override the static AWS Access Key ID | +| `AWS_ACCESS_KEY_ID` | `test` (`accountId`: 000000000000) | AWS Access Key ID to use for multi-account setups | + +:::note +While using `CUSTOMIZE_ACCESS_KEY`, following cases are taking precedence over each other from top to bottom: +1. If the `AWS_ACCESS_KEY_ID` environment variable is set. +2. If `access_key` is configured in the Terraform AWS provider. +3. If the `AWS_PROFILE` environment variable is set and properly configured. +4. If the `AWS_DEFAULT_PROFILE` environment variable is set and configured. +5. If credentials for the `default` profile are configured. +6. If none of the above settings are present, it falls back to using the default `AWS_ACCESS_KEY_ID` mock value. +::: + +### OpenTofu + +You can use the `TF_CMD` environment variable with `tflocal` to specify the `tofu` binary to call: + +```bash +TF_CMD=tofu tflocal --help +``` + +## samlocal + +`samlocal` is a wrapper for the `sam` command line interface, facilitating the use of the SAM framework with LocalStack. +When executing deployment commands like `samlocal [ build | deploy | validate | package ]`, the script configures the SAM settings for LocalStack and runs the specified SAM command. + +:::note +`samlocal` supports image/container-based Lambda (ECR) deploys and nested CloudFormation stacks, which `lstk sam` does not (yet) support - this is the main reason to keep using `samlocal` today. +::: + +### Installation + +You can install the `samlocal` wrapper script by running the following command: + +```bash +pip install aws-sam-cli-local +``` + +### Usage + +```bash +samlocal init +samlocal deploy --guided +``` + +### Configuration + +| Environment Variable | Default value | Description | +|------------------------|--------------------------------------------------|-------------------------------------------------------------------------| +| AWS_ENDPOINT_URL | `http://localhost.localstack.cloud:4566` | URL at which the `boto3` client can reach LocalStack | +| EDGE_PORT | `4566` | Port number under which the LocalStack edge service is available | +| LOCALSTACK_HOSTNAME | `localhost` | Host under which the LocalStack edge service is available + +## cdklocal + +`cdklocal` is a thin wrapper script for using the [AWS CDK](https://github.com/aws/aws-cdk) library against local APIs provided by LocalStack. + +### Installation + +The `cdklocal` command line is published as an [npm library](https://www.npmjs.com/package/aws-cdk-local): + +```bash +# Install globally +npm install -g aws-cdk-local aws-cdk + +# Verify it installed correctly +cdklocal --version +# e.g. 1.65.5 +``` + +:::note +Using `cdklocal` locally (e.g. within the `node_modules` of your repo instead of globally installed) does not work at the moment for some setups, so make sure you install both `aws-cdk` and `aws-cdk-local` with the `-G` flag. +::: + +### Usage + +`cdklocal` can be used as a drop-in replacement of where you would otherwise use `cdk` when targeting the AWS Cloud. + +```bash +cdklocal --help + +# create sample app +mkdir /tmp/test; cd /tmp/test +cdklocal init sample-app --language=javascript + +# bootstrap localstack environment +cdklocal bootstrap + +# deploy the sample app +cdklocal deploy +``` + +### Configuration + +The following environment variables can be configured: + +- `AWS_ENDPOINT_URL`: The endpoint URL (i.e., protocol, host, and port) to connect to LocalStack (default: `http://localhost.localstack.cloud:4566`) +- `LAMBDA_MOUNT_CODE`: Whether to use local Lambda code mounting (via setting `hot-reload` S3 bucket name) + +### CDK Version Compatibility + +`cdklocal` works with all installed versions of the Node.js `aws-cdk` package. +However, issues exist for `aws-cdk >= 2.177.0`. + +For these versions: + +- We unset AWS-related environment variables like `AWS_PROFILE` before calling `cdk`. +- We explicitly set `AWS_ENDPOINT_URL` and `AWS_ENDPOINT_URL_S3` to point to LocalStack. + +Some environment variables may cause conflicting config, such as wrong region or accidental deploys to real AWS. +To allow specific variables (e.g., `AWS_REGION`), use `AWS_ENVAR_ALLOWLIST`: + +```bash +AWS_ENVAR_ALLOWLIST=AWS_REGION,AWS_DEFAULT_REGION AWS_DEFAULT_REGION=eu-central-1 AWS_REGION=eu-central-1 cdklocal ... +``` + +If you manually set `AWS_ENDPOINT_URL`, it will be used. +You must also set `AWS_ENDPOINT_URL_S3`, and it must include `.s3.` to correctly identify S3 API calls. +See full configuration details [on our configuration docs](https://github.com/localstack/aws-cdk-local?tab=readme-ov-file#configurations). diff --git a/src/content/docs/aws/connecting/infrastructure-as-code/former2.md b/src/content/docs/aws/connecting/infrastructure-as-code/former2.md index 7dc545b00..a766f24d8 100644 --- a/src/content/docs/aws/connecting/infrastructure-as-code/former2.md +++ b/src/content/docs/aws/connecting/infrastructure-as-code/former2.md @@ -26,7 +26,7 @@ These outputs enable you to redeploy your resources while spinning a new LocalSt ## Getting started -This guide is designed for users new to Former2 and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Former2 and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. We will demonstrate how you can create local AWS resources using LocalStack, and import a CloudFormation output via Former2. ### Install Former2 @@ -49,13 +49,13 @@ Start your LocalStack container using your preferred method with the following e - **Mozilla Firefox**: `EXTRA_CORS_ALLOWED_ORIGINS=moz-extension://853c673f-1bd8-4226-a5ff-f1473f7b3d90` - **Microsoft Edge**: `EXTRA_CORS_ALLOWED_ORIGINS=extension://okkjnfohglnomdbpimkcdkiojbeiedof` -You can create local AWS resources using the AWS CLI and the `awslocal` wrapper script. +You can create local AWS resources using the AWS CLI and `lstk aws`. For example, you can create a new S3 bucket, SQS queue, and DynamoDB table using the following commands: ```bash -awslocal s3 mb s3://my-bucket -awslocal sqs create-queue --queue-name my-queue -awslocal dynamodb create-table \ +lstk aws s3 mb s3://my-bucket +lstk aws sqs create-queue --queue-name my-queue +lstk aws dynamodb create-table \ --table-name my-table \ --attribute-definitions AttributeName=id,AttributeType=S \ --key-schema AttributeName=id,KeyType=HASH \ @@ -65,19 +65,19 @@ awslocal dynamodb create-table \ You can verify that the resources were created successfully by running the following command: ```bash -localstack logs +lstk logs ``` ```bash title="Output" -2023-10-14T15:31:08.852 INFO --- [ asgi_gw_0] localstack.request.aws : AWS s3.CreateBucket => 200 -2023-10-14T15:31:09.356 INFO --- [ asgi_gw_0] localstack.request.aws : AWS sqs.CreateQueue => 200 -2023-10-14T15:31:12.920 INFO --- [ asgi_gw_0] botocore.credentials : Found credentials in environment variables. -2023-10-14T15:31:13.332 INFO --- [ asgi_gw_0] localstack.utils.bootstrap : Execution of "require" took 2028.25ms -2023-10-14T15:31:13.712 INFO --- [ asgi_gw_0] localstack.request.aws : AWS dynamodb.CreateTable => 200 +emulator | 2023-10-14T15:31:08.852 INFO --- [ asgi_gw_0] localstack.request.aws : AWS s3.CreateBucket => 200 +emulator | 2023-10-14T15:31:09.356 INFO --- [ asgi_gw_0] localstack.request.aws : AWS sqs.CreateQueue => 200 +emulator | 2023-10-14T15:31:12.920 INFO --- [ asgi_gw_0] botocore.credentials : Found credentials in environment variables. +emulator | 2023-10-14T15:31:13.332 INFO --- [ asgi_gw_0] localstack.utils.bootstrap : Execution of "require" took 2028.25ms +emulator | 2023-10-14T15:31:13.712 INFO --- [ asgi_gw_0] localstack.request.aws : AWS dynamodb.CreateTable => 200 ``` ```bash -awslocal s3 ls +lstk aws s3 ls ``` ```bash title="Output" @@ -85,7 +85,7 @@ awslocal s3 ls ``` ```bash -awslocal sqs list-queues +lstk aws sqs list-queues ``` ```bash title="Output" @@ -97,7 +97,7 @@ awslocal sqs list-queues ``` ```bash -awslocal dynamodb list-tables +lstk aws dynamodb list-tables ``` ```bash title="Output" diff --git a/src/content/docs/aws/connecting/infrastructure-as-code/pulumi.mdx b/src/content/docs/aws/connecting/infrastructure-as-code/pulumi.mdx index 7c6107618..6e3419d26 100644 --- a/src/content/docs/aws/connecting/infrastructure-as-code/pulumi.mdx +++ b/src/content/docs/aws/connecting/infrastructure-as-code/pulumi.mdx @@ -444,7 +444,7 @@ pulumi up After the update, check the S3 buckets with: ```bash -awslocal s3 ls +lstk aws s3 ls ``` You should see output similar to: diff --git a/src/content/docs/aws/connecting/infrastructure-as-code/serverless-framework.md b/src/content/docs/aws/connecting/infrastructure-as-code/serverless-framework.md index 8c45ec9ea..86852dc63 100644 --- a/src/content/docs/aws/connecting/infrastructure-as-code/serverless-framework.md +++ b/src/content/docs/aws/connecting/infrastructure-as-code/serverless-framework.md @@ -20,7 +20,7 @@ In particular, the setup consists of the following two steps. This guide assumes that you have the following tools installed. -- LocalStack ([Install](/aws/getting-started/installation)) +- The `lstk` CLI ([Install](/aws/developer-tools/running-localstack/lstk/#installation)) - Serverless ([Install](https://www.serverless.com/framework/docs/getting-started/)) It also assumes that you already have a Serverless app set up consisting of a couple of Lambda functions and a `serverless.yml` file similar to the following. @@ -134,7 +134,7 @@ You can now deploy your Serverless service to LocalStack. First, start LocalStack by running ```bash -localstack start +lstk start ``` Then deploy the endpoint by running diff --git a/src/content/docs/aws/connecting/infrastructure-as-code/terraform.mdx b/src/content/docs/aws/connecting/infrastructure-as-code/terraform.mdx index 568dbb700..4304fc3be 100644 --- a/src/content/docs/aws/connecting/infrastructure-as-code/terraform.mdx +++ b/src/content/docs/aws/connecting/infrastructure-as-code/terraform.mdx @@ -17,17 +17,21 @@ HCL is a domain-specific language designed for writing configurations that defin LocalStack supports Terraform via the [AWS provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) through [custom service endpoints](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/guides/custom-service-endpoints#localstack). You can configure Terraform to use LocalStack in two ways: -- Using the [`tflocal` wrapper script](https://github.com/localstack/terraform-local) to automatically configure the service endpoints for you. +- Using [`lstk terraform`](/aws/developer-tools/running-localstack/lstk/#terraform) (alias `lstk tf`) to automatically configure the service endpoints for you. - Manually configuring the service endpoints in your Terraform configuration with additional maintenance. -In this guide, we will demonstrate how you can create local AWS resources using Terraform and LocalStack, by using the `tflocal` wrapper script and a manual configuration example. +In this guide, we will demonstrate how you can create local AWS resources using Terraform and LocalStack, by using `lstk terraform` and a manual configuration example. -## `tflocal` wrapper script +## `lstk terraform` -`tflocal` is a small wrapper script to run Terraform against LocalStack. `tflocal` script uses the [Terraform Override mechanism](https://www.terraform.io/language/files/override) and creates a temporary file `localstack_providers_override.tf` to configure the endpoints for the AWS `provider` section. +`lstk terraform` (alias `lstk tf`) runs Terraform against LocalStack. It uses the [Terraform Override mechanism](https://www.terraform.io/language/files/override) and creates a temporary file `localstack_providers_override.tf` to configure the endpoints for the AWS `provider` section, then forwards your arguments to the real `terraform` binary. The endpoints for all services are configured to point to the LocalStack API (`http://localhost:4566` by default). It allows you to easily deploy your unmodified Terraform scripts against LocalStack. +:::note +`lstk terraform` supersedes the older [`tflocal` wrapper script](/aws/connecting/infrastructure-as-code/deprecated-wrapper-scripts#tflocal), which is deprecated but still available if you need it. +::: + ### Create a Terraform configuration Create a new file named `main.tf` and add a minimal S3 bucket configuration to it. @@ -39,18 +43,15 @@ resource "aws_s3_bucket" "test-bucket" { } ``` -### Install the `tflocal` wrapper script +### Install lstk -To install the `tflocal` command, you can use `pip` (assuming you have a local Python installation): +To use `lstk terraform`, install `lstk` by following the [`lstk` installation instructions](/aws/developer-tools/running-localstack/lstk/#installation). +You'll also need the [`terraform` CLI](https://developer.hashicorp.com/terraform/install) itself installed and on your `PATH`. -```bash -pip install terraform-local -``` - -After installation, you can use the `tflocal` command, which has the same interface as the `terraform` command line. +Once installed, you can use `lstk terraform`, which has the same interface as the `terraform` command line. ```bash -tflocal --help +lstk terraform --help ``` ```bash title="Output" @@ -64,43 +65,36 @@ Start your LocalStack container using your preferred method. Initialize Terraform using the following command: ```bash -tflocal init +lstk terraform init ``` You can now provision the S3 bucket specified in the configuration: ```bash -tflocal apply +lstk terraform apply ``` ### Configuration -| Environment Variable | Default value | Description | -| ------------------------ | -------------------------------- | ----------- | -| `TF_CMD` | `terraform` | Terraform command to call | -| `AWS_ENDPOINT_URL` | - | Hostname and port of the target LocalStack instance | -| `LOCALSTACK_HOSTNAME` | `localhost` | **(Deprecated)** Host name of the target LocalStack instance | -| `EDGE_PORT` | `4566` | **(Deprecated)** Port number of the target LocalStack instance | -| `S3_HOSTNAME` | `s3.localhost.localstack.cloud` | Special hostname to be used to connect to LocalStack S3 | -| `USE_EXEC` | - | Whether to use `os.exec` instead of `subprocess.Popen` (try using this in case of I/O issues) | -| `_ENDPOINT` | - | Setting a custom service endpoint, e.g., `COGNITO_IDP_ENDPOINT=http://example.com` | -| `AWS_DEFAULT_REGION` | `us-east-1` | The AWS region to use (determined from local credentials if `boto3` is installed) | -| `CUSTOMIZE_ACCESS_KEY` | - | Enables you to override the static AWS Access Key ID | -| `AWS_ACCESS_KEY_ID` | `test` (`accountId`: 000000000000) | AWS Access Key ID to use for multi-account setups | +The `lstk terraform` command supports several options and environment variables beyond what is available with standard `terraform`. Flags that are specific to `lstk terraform` must appear **before** the Terraform action: -:::note -While using `CUSTOMIZE_ACCESS_KEY`, following cases are taking precedence over each other from top to bottom: -1. If the `AWS_ACCESS_KEY_ID` environment variable is set. -2. If `access_key` is configured in the Terraform AWS provider. -3. If the `AWS_PROFILE` environment variable is set and properly configured. -4. If the `AWS_DEFAULT_PROFILE` environment variable is set and configured. -5. If credentials for the `default` profile are configured. -6. If none of the above settings are present, it falls back to using the default `AWS_ACCESS_KEY_ID` mock value. -::: +| Option | Description | +| ---------------------- | ----------- | +| `--region ` | Deployment region | +| `--account ` | Target AWS account id (12 digits) | + +| Environment Variable | Default value | Description | +| ------------------------------ | ------------------------------------- | ----------- | +| `AWS_ENDPOINT_URL` | - | Override the auto-resolved LocalStack endpoint | +| `LSTK_TF_CMD` | `terraform` | Binary to invoke, e.g. `tofu` | +| `LSTK_TF_OVERRIDE_FILE_NAME` | `localstack_providers_override.tf` | Override file name | +| `LSTK_TF_DRY_RUN` | - | When set, generate the override file but do not run Terraform | +| `AWS_REGION` | - | Fallback for `--region` | +| `AWS_ACCESS_KEY_ID` | - | Fallback for `--account` | ## Manual Configuration -Instead of using the `tflocal` script, you have the option to manually configure the local service endpoints and credentials. +Instead of using `lstk terraform`, you have the option to manually configure the local service endpoints and credentials. The following sections will provide detailed steps for this manual configuration. ### General Configuration @@ -182,7 +176,7 @@ resource "aws_s3_bucket" "test-bucket" { ### Endpoint Configuration Here's a configuration example with additional service endpoints. -Please note that these provider configurations may not be necessary if you use the `tflocal` script (as described above). +Please note that these provider configurations may not be necessary if you use `lstk terraform` (as described above). You can save the following configuration in a file named `provider.tf` and include it in your Terraform configuration. ```hcl showshowLineNumbers @@ -238,10 +232,10 @@ If you use a different account ID within LocalStack, you can customize the snipp ## OpenTofu -OpenTofu is an open-source fork of Terraform acting as a drop-in replacement for Terraform, as it's compatible with Terraform versions 1.5.x and most of 1.6.x. You can use OpenTofu with LocalStack to create and manage your AWS resources with your pre-existing Terraform configurations. You can use the `TF_CMD` environment variable with `tflocal` to specify the `tofu` binary to call, or setup a manual configuration to point the individual services to LocalStack. +OpenTofu is an open-source fork of Terraform acting as a drop-in replacement for Terraform, as it's compatible with Terraform versions 1.5.x and most of 1.6.x. You can use OpenTofu with LocalStack to create and manage your AWS resources with your pre-existing Terraform configurations. You can use the `LSTK_TF_CMD` environment variable with `lstk terraform` to specify the `tofu` binary to call, or setup a manual configuration to point the individual services to LocalStack. ```bash -TF_CMD=tofu tflocal --help +LSTK_TF_CMD=tofu lstk terraform --help ``` ```bash title="Output" diff --git a/src/content/docs/aws/customization/advanced/arm64-support.md b/src/content/docs/aws/customization/advanced/arm64-support.md index f07b7f765..089f96102 100644 --- a/src/content/docs/aws/customization/advanced/arm64-support.md +++ b/src/content/docs/aws/customization/advanced/arm64-support.md @@ -12,7 +12,7 @@ This manifest contains links to a Linux AMD64 as well as a Linux ARM64 image. ## Pulling the LocalStack image -With the multi-arch Docker manifest, your Docker client (and therefore the [LocalStack CLI](/aws/getting-started/installation/#localstack-cli)) now automatically selects the image according to your platform: +With the multi-arch Docker manifest, your Docker client (and therefore [`lstk`](/aws/developer-tools/running-localstack/lstk)) now automatically selects the image according to your platform: ```bash docker pull localstack/localstack diff --git a/src/content/docs/aws/customization/advanced/cross-account-access.md b/src/content/docs/aws/customization/advanced/cross-account-access.md index 32bd17afb..906c91867 100644 --- a/src/content/docs/aws/customization/advanced/cross-account-access.md +++ b/src/content/docs/aws/customization/advanced/cross-account-access.md @@ -13,14 +13,17 @@ This document provides information to help design such setups. :::note Cross-account support in LocalStack is being actively developed. -Please report any issues on our [GitHub Discussions board](https://github.com/orgs/localstack/discussions/categories/bugs). +Please report any issues to [LocalStack Support](/aws/help-support/get-help). ::: Cross-account/cross-region access happens when a client attempts to access a resource in another account or region than what it is configured with: +The examples below select the account with the `--account` flag of `lstk aws`. +You can also set the account ID through the `AWS_ACCESS_KEY_ID` environment variable, for example `AWS_ACCESS_KEY_ID=111111111111 lstk aws ...`. + ```bash # Create a queue in one account and region -AWS_ACCESS_KEY_ID=111111111111 awslocal sqs create-queue \ +lstk aws --account 111111111111 sqs create-queue \ --queue-name my-queue \ --region ap-south-1 ``` @@ -33,14 +36,14 @@ AWS_ACCESS_KEY_ID=111111111111 awslocal sqs create-queue \ ```bash # Set some attributes -AWS_ACCESS_KEY_ID=111111111111 awslocal sqs set-queue-attributes \ +lstk aws --account 111111111111 sqs set-queue-attributes \ --attributes VisibilityTimeout=60 \ --queue-url http://sqs.ap-south-1.localhost.localstack.cloud:443/111111111111/my-queue \ --region ap-south-1 # Retrieve the queue attribute from another account and region # The required information for LocalStack to locate the queue is available in the queue URL -AWS_ACCESS_KEY_ID=222222222222 awslocal sqs get-queue-attributes \ +lstk aws --account 222222222222 sqs get-queue-attributes \ --attribute-names VisibilityTimeout \ --region eu-central-1 \ --queue-url http://sqs.ap-south-1.localhost.localstack.cloud:443/111111111111/my-queue diff --git a/src/content/docs/aws/customization/advanced/filesystem.mdx b/src/content/docs/aws/customization/advanced/filesystem.mdx index cd00e0833..14a71fd61 100644 --- a/src/content/docs/aws/customization/advanced/filesystem.mdx +++ b/src/content/docs/aws/customization/advanced/filesystem.mdx @@ -100,12 +100,17 @@ In this case, the effective layout would be something like: - zipfile.4986fb95 -### Using the CLI +### Using lstk -When using the CLI to start LocalStack, the volume directory can be configured via the `LOCALSTACK_VOLUME_DIR`. -It should point to a directory on the host which is then automatically mounted into `/var/lib/localstack`. -The defaults are: +When using [`lstk`](/aws/developer-tools/running-localstack/lstk) to start LocalStack, the volume directory is configured with the `volume` field on a container block. +It should point to a directory on the host which is then automatically mounted into `/var/lib/localstack`: -- Mac: `~/Library/Caches/localstack/volume` -- Linux: `~/.cache/localstack/volume` -- Windows: `%LOCALAPPDATA%\cache\localstack\volume` +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +volume = "./volume" +``` + +If `volume` is not set, `lstk` defaults to `/lstk/volume/`. +Run [`lstk volume path`](/aws/developer-tools/running-localstack/lstk#volume) to print the resolved directory. diff --git a/src/content/docs/aws/customization/advanced/initialization-hooks.mdx b/src/content/docs/aws/customization/advanced/initialization-hooks.mdx index 7f592dfc3..547dc4e83 100644 --- a/src/content/docs/aws/customization/advanced/initialization-hooks.mdx +++ b/src/content/docs/aws/customization/advanced/initialization-hooks.mdx @@ -117,21 +117,22 @@ A common use case for init hooks is pre-seeding LocalStack with custom state. For example if you want to have a certain S3 bucket or DynamoDB table created when starting LocalStack, init hooks can be very useful. :::tip -If you have more complex states, [Cloud Pods](/aws/developer-tools/snapshots/cloud-pods) and [how to auto-load them on startup](/aws/developer-tools/snapshots/cloud-pods#auto-loading-cloud-pods) may be a good option to look into! +If you have more complex states, [Cloud Pods](/aws/developer-tools/snapshots/cloud-pods) and [how to auto-load them on startup](/aws/developer-tools/snapshots/cloud-pods#auto-loading-from-cloud-pods) may be a good option to look into! ::: To execute aws cli commands when LocalStack becomes ready, simply create a script `init-aws.sh` and mount it into `/etc/localstack/init/ready.d/`. Make sure the script is executable: run `chmod +x init-aws.sh` on the file first. -You can use anything available inside the container, including `awslocal`: +You can use anything available inside the container, and can install new software: ```bash #!/bin/bash -export AWS_ACCESS_KEY_ID=000000000000 AWS_SECRET_ACCESS_KEY=000000000000 +npm install -g @localstack/lstk +lstk setup aws -awslocal s3 mb s3://my-bucket -awslocal sqs create-queue --queue-name my-queue +lstk aws s3 mb s3://my-bucket +lstk aws sqs create-queue --queue-name my-queue ``` Start Localstack: @@ -153,11 +154,22 @@ services: - "/var/run/docker.sock:/var/run/docker.sock" ``` - -```bash -# DOCKER_FLAGS are additional parameters to the `docker run` command of localstack start + +Declare the bind mount and the `DEBUG` profile in your config file, then start LocalStack: + +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +env = ["debug"] +volumes = ["/path/to/init-aws.sh:/etc/localstack/init/ready.d/init-aws.sh"] + +[env.debug] +DEBUG = "1" +``` -DOCKER_FLAGS='-v /path/to/init-aws.sh:/etc/localstack/init/ready.d/init-aws.sh' localstack start +```bash +lstk start ``` @@ -172,8 +184,8 @@ and for more details on running init hooks in development mode, you can check ou Start LocalStack with **`EXTENSION_AUTO_INSTALL="localstack-extension-terraform-init"`**. Mount a **`main.tf`** file into **`/etc/localstack/init/ready.d`** -When LocalStack starts up, it will install the extension, which in turn installs Terraform and [`tflocal`](https://github.com/localstack/terraform-local) into the container. -If one of the init stage directories contain a `main.tf` file, the extension will run `tflocal init` and `tflocal apply` on that directory. +When LocalStack starts up, it will install the extension, which in turn installs Terraform into the container. +If one of the init stage directories contain a `main.tf` file, the extension will run `terraform init` and `terraform apply` on that directory. ```terraform # main.tf @@ -210,11 +222,20 @@ services: - "/var/run/docker.sock:/var/run/docker.sock" ``` - + +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +env = ["terraform-init"] +volumes = ["./main.tf:/etc/localstack/init/ready.d/main.tf"] + +[env.terraform-init] +EXTENSION_AUTO_INSTALL = "localstack-extension-terraform-init" +``` + ```bash -localstack start \ - -e EXTENSION_AUTO_INSTALL="localstack-extension-terraform-init" \ - -v ./main.tf:/etc/localstack/init/ready.d/main.tf +lstk start ``` @@ -222,7 +243,7 @@ localstack start \ You can wait for LocalStack to complete the startup process, and then print the created S3 bucket: ```bash -localstack wait && awslocal s3 ls +lstk aws s3 ls ``` The logs should show something like: diff --git a/src/content/docs/aws/customization/advanced/multi-account-setups.md b/src/content/docs/aws/customization/advanced/multi-account-setups.md index edecce812..b31465692 100644 --- a/src/content/docs/aws/customization/advanced/multi-account-setups.md +++ b/src/content/docs/aws/customization/advanced/multi-account-setups.md @@ -8,7 +8,7 @@ sidebar: :::note Please note that multi-accounts may not work for use-cases that have cross-account and cross-service access. -Please open a [GitHub Discussion](https://github.com/orgs/localstack/discussions/new/choose) to request and upvote for support for specific use-cases. +Please contact [LocalStack Support](/aws/help-support/get-help) to request support for specific use-cases. ::: LocalStack ships with multi-account support which allows namespacing based on AWS account ID. @@ -20,14 +20,13 @@ The Access Key ID field can be configured in the AWS CLI in multiple ways: pleas ## Examples -In following examples, we configure the AWS CLI account ID via environment variable. +In the following examples, we select the account ID with the `--account` flag of `lstk aws`. ```bash -AWS_ACCESS_KEY_ID=000000000001 awslocal ec2 create-key-pair --key-name green-hospital +lstk aws --account 000000000001 ec2 create-key-pair --key-name green-hospital +lstk aws --account 000000000002 ec2 create-key-pair --key-name red-medicine -AWS_ACCESS_KEY_ID=000000000002 awslocal ec2 create-key-pair --key-name red-medicine - -AWS_ACCESS_KEY_ID=000000000001 awslocal ec2 describe-key-pairs +lstk aws --account 000000000001 ec2 describe-key-pairs { "KeyPairs": [ { @@ -37,7 +36,7 @@ AWS_ACCESS_KEY_ID=000000000001 awslocal ec2 describe-key-pairs ] } -AWS_ACCESS_KEY_ID=000000000002 awslocal ec2 describe-key-pairs +lstk aws --account 000000000002 ec2 describe-key-pairs { "KeyPairs": [ { @@ -48,11 +47,17 @@ AWS_ACCESS_KEY_ID=000000000002 awslocal ec2 describe-key-pairs } ``` +Alternatively, you can set the account ID through the `AWS_ACCESS_KEY_ID` environment variable: + +```bash +AWS_ACCESS_KEY_ID=000000000001 lstk aws ec2 describe-key-pairs +``` + If no explicit Account ID is set, LocalStack falls back to default. In this example, no resources are returned. ```bash -awslocal ec2 describe-key-pairs +lstk aws ec2 describe-key-pairs { "KeyPairs": [] } diff --git a/src/content/docs/aws/customization/advanced/usage-tracking.md b/src/content/docs/aws/customization/advanced/usage-tracking.md index 45e5364d1..449b4a570 100644 --- a/src/content/docs/aws/customization/advanced/usage-tracking.md +++ b/src/content/docs/aws/customization/advanced/usage-tracking.md @@ -96,7 +96,7 @@ Here is an example of a CLI invocation event: "client_time": "2022-08-30 14:46:54.116457" }, "payload": { - "cmd": "localstack config validate", + "cmd": "lstk start", "params": [ "file" ] diff --git a/src/content/docs/aws/customization/configuration-options.md b/src/content/docs/aws/customization/configuration-options.md index 7b915a7c8..41bfffed9 100644 --- a/src/content/docs/aws/customization/configuration-options.md +++ b/src/content/docs/aws/customization/configuration-options.md @@ -6,17 +6,33 @@ template: doc LocalStack exposes various configuration options to control its behaviour. -These options can be passed to LocalStack as environment variables like so: +With `lstk`, these options can be passed as `LOCALSTACK_`-prefixed environment variables when starting the container: ```bash -DEBUG=1 localstack start +LOCALSTACK_DEBUG=1 lstk start ``` +Alternatively, set them as named environment profiles in your config file and reference them from the container block: + +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +env = ["debug"] + +[env.debug] +DEBUG = "1" +``` + +```bash +lstk start +``` + +See [Passing environment variables to the container](/aws/developer-tools/running-localstack/lstk#passing-environment-variables-to-the-container) for details. + To facilitate interoperability, configuration variables can be prefixed with `LOCALSTACK_` in docker. For instance, setting `LOCALSTACK_PERSISTENCE=1` is equivalent to `PERSISTENCE=1`. -You can also use [Profiles](#profiles). - Configurations marked as **Deprecated** will be removed in the next major version. You can find previously removed configuration variables under [Legacy](#legacy). @@ -44,13 +60,8 @@ Options that affect the core LocalStack system. ## CLI -These options are applicable when using the CLI to start LocalStack. - -| Variable | Example Values | Description | -| - | - | - | -| `LOCALSTACK_VOLUME_DIR` | `~/.cache/localstack/volume` (on Linux) | The location on the host of the LocalStack volume directory mount. See [Filesystem Layout](/aws/customization/advanced/filesystem#using-the-cli) | -| `CONFIG_PROFILE` | | The configuration profile to load. See [Profiles](#profiles) | -| `CONFIG_DIR` | `~/.localstack` | The path where LocalStack can find configuration profiles and other CLI-specific configuration | +`lstk` is configured through its config file rather than through environment variables. +See [Configuration](/aws/developer-tools/running-localstack/lstk#configuration) on the `lstk` page for the config file search order, the field reference, and how to define named environment profiles. ## Docker @@ -58,6 +69,7 @@ Options to configure how LocalStack interacts with Docker. | Variable | Example Values | Description | | - | - | - | +| `LOCALSTACK_VOLUME_DIR` | `~/.cache/localstack/volume` (on Linux) | The location on the host of the LocalStack volume directory mount. See [Filesystem Layout](/aws/customization/advanced/filesystem) | | `DOCKER_FLAGS` | | Allows to pass custom flags (e.g., volume mounts) to "docker run" when running LocalStack in Docker. | | `DOCKER_SOCK` | `/var/run/docker.sock` | Path to local Docker UNIX domain socket | | `DOCKER_BRIDGE_IP` | `172.17.0.1` | IP of the docker bridge used to enable access between containers | @@ -397,7 +409,7 @@ To learn more about these configuration options, see [Persistence](/aws/develope | `SNAPSHOT_SAVE_STRATEGY` | `ON_SHUTDOWN`\|`ON_REQUEST`\|`SCHEDULED`\|`MANUAL` | Strategy that governs when LocalStack should make state snapshots | | `SNAPSHOT_LOAD_STRATEGY` | `ON_STARTUP`\|`ON_REQUEST`\|`MANUAL` | Strategy that governs when LocalStack restores state snapshots | | `SNAPSHOT_FLUSH_INTERVAL` | 15 (default) | The interval (in seconds) between persistence snapshots. It only applies to a `SCHEDULED` save strategy (see [Persistence Mechanism](/aws/developer-tools/snapshots/persistence))| -| `DISABLE_COMPATIBILITY_RULES` | `0` (default) \| `1` | Disable the [state compatibility rules](/aws/developer-tools/snapshots/persistence#state-compatibility) that prevent loading incompatible state into LocalStack. Applies to both snapshot persistence and Cloud Pods. | +| `DISABLE_COMPATIBILITY_RULES` | `0` (default) \| `1` | Disable the [snapshot compatibility rules](/aws/developer-tools/snapshots/service-coverage#snapshot-compatibility) that prevent loading incompatible state into LocalStack. Applies to both snapshot persistence and Cloud Pods. | ## Cloud Pods @@ -409,7 +421,7 @@ To learn more about these configuration options, see [Cloud Pods](/aws/developer | `POD_LOAD_CLI_TIMEOUT` | 60 (default) | Timeout in seconds to wait before returning from load operations on the Cloud Pods CLI | | `POD_ENCRYPTION` | `0` (default) \| `1` | Whether to encrypt the Cloud Pods artifacts at rest. | | `ENABLE_POD_RESOURCES=1` | `0` (default) \| `1` | Whether to save a detailed Stack Overview including available resources for the Cloud Pod | -| `MERGE_STRATEGY` | `account-region-merge` (default) \| `service-merge` \| `overwrite` | The merge strategy to apply when loading a Cloud Pod into LocalStack (see [state merging](/aws/developer-tools/snapshots/cloud-pods/#state-merging)) | +| `MERGE_STRATEGY` | `account-region-merge` (default) \| `service-merge` \| `overwrite` | The merge strategy to apply when loading a Cloud Pod into LocalStack (see [merging snapshots](/aws/developer-tools/snapshots/merging-snapshots/)) | ## Extensions @@ -534,51 +546,3 @@ These configurations have already been removed and **won't have any effect** on | `TMPDIR`| 2.0.0 | `/tmp` (default) | Temporary folder on the host running the CLI and inside the LocalStack container .| | `USE_LIGHT_IMAGE` | 2.0.0 | `1` (default) | Whether to use the light-weight Docker image. Overwritten by `IMAGE_NAME`.| | `PORT_WEB_UI` | 0.12.8 | `8080` (default) | Port for the legacy Web UI. Replaced by our [Web Application](https://app.localstack.cloud) | - -## Profiles - -LocalStack supports configuration profiles which are stored in the `~/.localstack` config directory. -If the directory does not exist, create it manually. -A configuration profile is a set of environment variables stored in an `.env` file in the LocalStack config directory. - -Here is an example of what configuration profiles might look like: - -```bash -tree ~/.localstack -/home/username/.localstack -├── default.env -├── dev.env -└── pro.env -``` - -Here is an example of what a specific environment profile looks like - -```bash -cat ~/.localstack/pro-debug.env -LOCALSTACK_AUTH_TOKEN=XXXXX -DEBUG=1 -DEVELOP=1 -``` - -You can load a profile by either setting the `env` variable `CONFIG_PROFILE=` or the `--profile=` CLI flag when using the CLI. -Let's take an example to load the `dev.env` profile file if it exists: - -```bash -python -m localstack.cli.main --profile=dev start -``` - -If no profile is specified, the `default.env` profile will be loaded. -While explicitly specified, the environment variables will always overwrite the profile. - -To display the config environment variables, you can use the following command: - -```bash -python -m localstack.cli.main --profile=dev config show -``` - -:::note -The `CONFIG_PROFILE` is a CLI feature and cannot be used with a Docker/Docker Compose setup. -You can look at [alternative means of setting environment variables](https://docs.docker.com/compose/environment-variables/set-environment-variables/) for your Docker Compose setups. - -For Docker setups, we recommend passing the environment variables directly to the `docker run` command. -::: diff --git a/src/content/docs/aws/customization/integrations/app-frameworks/aspire.md b/src/content/docs/aws/customization/integrations/app-frameworks/aspire.md index d9dbf2898..e003f0f4a 100644 --- a/src/content/docs/aws/customization/integrations/app-frameworks/aspire.md +++ b/src/content/docs/aws/customization/integrations/app-frameworks/aspire.md @@ -12,7 +12,7 @@ sidebar: With Aspire, developers can orchestrate cloud-native applications locally using the same AWS resources they deploy in production. By combining Aspire with LocalStack, teams can emulate their full cloud environment—including Lambda, SQS, S3, and DynamoDB—with minimal configuration and no AWS costs. -LocalStack integrates with Aspire through the [`LocalStack.Aspire.Hosting`](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack) package, enabling seamless local development and testing of AWS-powered applications within the Aspire orchestration framework. This package extends the official [AWS integrations for .NET Aspire](https://github.com/aws/customization/integrations-on-dotnet-aspire-for-aws) to provide LocalStack-specific functionality. +LocalStack integrates with Aspire through the [`LocalStack.Aspire.Hosting`](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack) package, enabling seamless local development and testing of AWS-powered applications within the Aspire orchestration framework. This package extends the official [AWS integrations for .NET Aspire](https://github.com/aws/integrations-on-dotnet-aspire-for-aws) to provide LocalStack-specific functionality. ## Getting started @@ -168,7 +168,7 @@ An event registration system showcasing distributed tracing and observability pa - [Aspire Documentation](https://aspire.dev/) - [LocalStack.Aspire.Hosting on GitHub](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack) - [LocalStack.Client on GitHub](https://github.com/localstack-dotnet/localstack-dotnet-client) -- [AWS Aspire Integration](https://github.com/aws/customization/integrations-on-dotnet-aspire-for-aws) +- [AWS Aspire Integration](https://github.com/aws/integrations-on-dotnet-aspire-for-aws) - [AWS SDK for .NET Documentation](https://docs.aws.amazon.com/sdk-for-net/) - [LocalStack Serverless .NET Demo](https://github.com/localstack-dotnet/localstack-serverless-dotnet-demo) - [OpenTelemetry with Aspire and LocalStack Demo](https://github.com/Blind-Striker/dotnet-otel-aspire-localstack-demo) diff --git a/src/content/docs/aws/customization/integrations/app-frameworks/selfmanaged-kafka-cluster.md b/src/content/docs/aws/customization/integrations/app-frameworks/selfmanaged-kafka-cluster.md index 041fa8175..e82b1bcea 100644 --- a/src/content/docs/aws/customization/integrations/app-frameworks/selfmanaged-kafka-cluster.md +++ b/src/content/docs/aws/customization/integrations/app-frameworks/selfmanaged-kafka-cluster.md @@ -22,7 +22,7 @@ docker-compose up -d 2. Create the Lambda function: ```bash showshowLineNumbers -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name fun1 \ --handler lambda.handler \ --runtime python3.8 \ @@ -54,7 +54,7 @@ awslocal lambda create-function \ 3. Create an example secret: ```bash showshowLineNumbers -awslocal secretsmanager create-secret --name localstack +lstk aws secretsmanager create-secret --name localstack { "ARN": "arn:aws:secretsmanager:us-east-1:000000000000:secret:localstack-TDIuI", "Name": "localstack", @@ -72,7 +72,7 @@ Created topic t1. 5. Create the event source mapping to your local kafka cluster: ```bash showshowLineNumbers -awslocal lambda create-event-source-mapping \ +lstk aws lambda create-event-source-mapping \ --topics t1 \ --source-access-configuration Type=SASL_SCRAM_512_AUTH,URI=arn:aws:secretsmanager:us-east-1:000000000000:secret:localstack-TDIuI \ --function-name arn:aws:lambda:us-east-1:000000000000:function:fun1 \ diff --git a/src/content/docs/aws/customization/integrations/extensions/developing-extensions.mdx b/src/content/docs/aws/customization/integrations/extensions/developing-extensions.mdx index 8a9aa5c6f..42c505219 100644 --- a/src/content/docs/aws/customization/integrations/extensions/developing-extensions.mdx +++ b/src/content/docs/aws/customization/integrations/extensions/developing-extensions.mdx @@ -150,6 +150,11 @@ reference points to the plugin class. ## Using the extensions developer CLI +:::note +The new CLI experience, `lstk`, does not support LocalStack Extensions. There is no `lstk extensions` command suite. +Continue using the legacy [LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/) for the commands in this section. +::: + The extensions CLI has a set of developer commands that allow you to create new extensions, and toggle local dev mode for extensions. Extensions that are toggled for developer mode will be mounted into the localstack container so you don't need to re-install them every time you change something. diff --git a/src/content/docs/aws/customization/integrations/extensions/index.md b/src/content/docs/aws/customization/integrations/extensions/index.md index 102905a2d..19d93b21f 100644 --- a/src/content/docs/aws/customization/integrations/extensions/index.md +++ b/src/content/docs/aws/customization/integrations/extensions/index.md @@ -31,4 +31,7 @@ Our [MailHog tutorial](/aws/customization/integrations/extensions/mailhog) teach :::note The feature and the API are currently in preview stage and may be subject to change. Please report any issues or feature requests on [LocalStack Extension's GitHub repository](https://github.com/localstack/localstack-extensions). + +The new CLI experience, `lstk`, does not support LocalStack Extensions. There is no `lstk extensions` command suite. +Continue using the legacy [LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/) to install, manage, and develop extensions. ::: diff --git a/src/content/docs/aws/customization/integrations/extensions/managing-extensions.mdx b/src/content/docs/aws/customization/integrations/extensions/managing-extensions.mdx index 1e0bb5df5..ea6139952 100644 --- a/src/content/docs/aws/customization/integrations/extensions/managing-extensions.mdx +++ b/src/content/docs/aws/customization/integrations/extensions/managing-extensions.mdx @@ -33,6 +33,11 @@ However, you may lose LocalStack state if you do not use persistence. ## Using the extensions CLI +:::note +The new CLI experience, `lstk`, does not support LocalStack Extensions. There is no `lstk extensions` command suite. +Continue using the legacy [LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/) for the commands in this section. +::: + If you use LocalStack with the CLI, you can also use our `localstack extensions` CLI command suite. To get a list of all available commands in LocalStack Extensions, run: diff --git a/src/content/docs/aws/customization/integrations/testing/lambdatest-hyperexecute.md b/src/content/docs/aws/customization/integrations/testing/lambdatest-hyperexecute.md index fde2c8c89..048313886 100644 --- a/src/content/docs/aws/customization/integrations/testing/lambdatest-hyperexecute.md +++ b/src/content/docs/aws/customization/integrations/testing/lambdatest-hyperexecute.md @@ -36,22 +36,24 @@ parallelism: 2 concurrency: 2 scenarioCommandStatusOnly: true runtime: - language: python - version: 3.10 + - language: python + version: '3.10' + - language: node + version: '18' pre: - - pip install localstack awscli awscli-local - - localstack start -d - - localstack wait -t 60 - - awslocal s3 mb s3://test-bucket - - awslocal sqs create-queue --queue-name test-queue - - awslocal sns create-topic --name test-topic + - npm install -g @localstack/lstk + - pip install awscli + - LOCALSTACK_AUTH_TOKEN=${{ .secrets.LOCALSTACK_AUTH_TOKEN }} lstk start --non-interactive --timeout 60s + - lstk aws s3 mb s3://test-bucket + - lstk aws sqs create-queue --queue-name test-queue + - lstk aws sns create-topic --name test-topic ``` The above minimal configuration file starts LocalStack and creates an S3 bucket, SQS queue, and SNS topic. :::note -To use the LocalStack for AWS image, configure a LocalStack Auth Token by appending `LOCALSTACK_AUTH_TOKEN=${{ .secrets.LOCALSTACK_AUTH_TOKEN }}` to the `localstack start` command. -Subsequently, you need to add your LocalStack Auth Token to your HyperExecute Portal as a secret. +`lstk` requires a LocalStack Auth Token, and CI environments need a [CI Auth Token](/aws/getting-started/auth-token/) rather than a personal Developer Token. +Add it to your HyperExecute Portal as a secret named `LOCALSTACK_AUTH_TOKEN` so `${{ .secrets.LOCALSTACK_AUTH_TOKEN }}` resolves at runtime. ::: ### Enabling test execution on HyperExecute diff --git a/src/content/docs/aws/customization/kubernetes/openshift.md b/src/content/docs/aws/customization/kubernetes/openshift.md index be460aea5..767245b19 100644 --- a/src/content/docs/aws/customization/kubernetes/openshift.md +++ b/src/content/docs/aws/customization/kubernetes/openshift.md @@ -23,7 +23,7 @@ If you have any questions or uncertainties regarding the licensing implications, ## Getting started -This guide is designed for users new to LocalStack and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to LocalStack and assumes basic knowledge of the AWS CLI and our [`lstk aws` AWS CLI proxy](/aws/developer-tools/running-localstack/lstk#aws). As a general prerequisite, you should have access to the [OpenShift Web Console](https://docs.openshift.com/container-platform/4.14/web_console/web-console-overview.html). We will demonstrate how you can create local AWS resources using LocalStack using the AWS CLI. @@ -69,25 +69,32 @@ Click on the **localstack-dev-spaces** pod to view the details. You will be able to see the exposed route for the LocalStack container. Copy the route URL and use it to interact with the LocalStack container. -To create an S3 bucket and an SQS queue, run the following commands: +Since LocalStack is running on the cluster rather than on your machine, point `lstk` at the exposed route instead of its default local endpoint. +Set `LSTK_ENDPOINT_URL` once for the whole session: ```bash -export AWS_ENDPOINT_URL='' -awslocal s3 mb s3://my-bucket -awslocal sqs create-queue --queue-name my-queue +export LSTK_ENDPOINT_URL='' +lstk aws s3 mb s3://my-bucket +lstk aws sqs create-queue --queue-name my-queue +``` + +Alternatively, pass the global `--endpoint-url` flag per command: + +```bash +lstk --endpoint-url '' aws s3 mb s3://my-bucket +lstk --endpoint-url '' aws sqs create-queue --queue-name my-queue ``` In the above commands, replace `` with the route URL of the LocalStack container. -The `AWS_ENDPOINT_URL` environment variable is used to specify the endpoint URL of the LocalStack container. :::note -By default, the endpoint URL for `awslocal` is `http://localhost:4566`. -Since we are running LocalStack on OpenShift, we need to specify the route URL of the LocalStack container. -You can swap `awslocal` with the AWS CLI, by specifying the additional `--endpoint-url` parameter. +By default, `lstk aws` targets the emulator on your local machine. +Since we are running LocalStack on OpenShift, we need to specify the route URL of the LocalStack container, using either `LSTK_ENDPOINT_URL` or `--endpoint-url`. +The flag takes precedence over the environment variable. ::: -You can further use integrations, such as [CDK](https://docs.localstack.cloud/user-guide/integrations/aws-cdk/), [SAM CLI](https://docs.localstack.cloud/user-guide/integrations/aws-sam/), and [Terraform](https://docs.localstack.cloud/user-guide/integrations/terraform/), to interact with the Ephemeral Instance. -In these integrations, you can change the `AWS_ENDPOINT_URL` environment variable to the endpoint URL of the Ephemeral Instance. +You can further use the other `lstk` tool proxies, such as [`lstk cdk`](/aws/developer-tools/running-localstack/lstk#cdk), [`lstk sam`](/aws/developer-tools/running-localstack/lstk#sam), and [`lstk terraform`](/aws/developer-tools/running-localstack/lstk#terraform), to interact with the deployment. +As with `lstk aws`, set `LSTK_ENDPOINT_URL` or pass `--endpoint-url` to point these at the route URL instead of a local emulator. ### Deleting the LocalStack deployment diff --git a/src/content/docs/aws/customization/logging.md b/src/content/docs/aws/customization/logging.md index 1684408c7..4b5fa7842 100644 --- a/src/content/docs/aws/customization/logging.md +++ b/src/content/docs/aws/customization/logging.md @@ -4,7 +4,7 @@ description: Control LocalStack log output, verbosity, and error reporting. template: doc --- -LocalStack supports logging output and error reporting through the `localstack` CLI or a Docker/Docker Compose based setup. +LocalStack supports logging output and error reporting through the `lstk` CLI or a Docker/Docker Compose based setup. LocalStack's logging setup allows you to: - Discover errors in your code during development & testing. @@ -52,11 +52,22 @@ Requests to HTTP endpoints are logged in a similar way. ## Log inspection -You can inspect the logs of the LocalStack container using the `localstack` CLI or your Docker/Docker Compose setup. -With the `localstack` CLI, you can run the following command to inspect the logs of the LocalStack container: +You can inspect the logs of the LocalStack container using [`lstk`](/aws/developer-tools/running-localstack/lstk) or your Docker/Docker Compose setup. +With `lstk`, you can run the following command to inspect the logs of the LocalStack container: ```bash -localstack logs +lstk logs +``` + +By default this prints the currently available logs, with noisy internal lines filtered out. +Add `--follow` to stream logs in real time, and `--verbose` to show every line unfiltered: + +```bash +# Stream filtered logs in real-time +lstk logs --follow + +# Stream all logs without filtering +lstk logs --follow --verbose ``` With Docker/Docker-Compose, you can run `docker ps` to get the container ID of the LocalStack container and then run `docker logs ` to inspect the logs. diff --git a/src/content/docs/aws/customization/networking/accessing-endpoint-url.mdx b/src/content/docs/aws/customization/networking/accessing-endpoint-url.mdx index 36ace0ab8..7f9c32759 100644 --- a/src/content/docs/aws/customization/networking/accessing-endpoint-url.mdx +++ b/src/content/docs/aws/customization/networking/accessing-endpoint-url.mdx @@ -16,7 +16,7 @@ This documentation provides step-by-step guidance on how to access LocalStack se Suppose you have LocalStack installed on your machine and want to access it using the AWS CLI. To connect, you must expose port 4566 from your LocalStack instance and connect to `localhost` or a domain name that points to `localhost`. -While the LocalStack CLI does this automatically, when running the Docker container directly or with docker compose, you must configure it manually. +While [`lstk`](/aws/developer-tools/running-localstack/lstk) does this automatically, when running the Docker container directly or with docker compose, you must configure it manually. Check out the [getting started documentation](/aws/getting-started/installation) for more information. :::tip @@ -93,7 +93,6 @@ All subdomains of `localhost.localstack.cloud` will also resolve to the LocalSta To configure your application container: -* add a user-managed docker network; * either determine your LocalStack container IP, or configure your LocalStack container to have a fixed known IP address; * set the DNS server of your application container to the IP address of the LocalStack container. @@ -101,16 +100,15 @@ To configure your application container: ```bash # start localstack -localstack start -d --network ls -localstack wait +lstk start # get the ip address of the LocalStack container -docker inspect localstack-main | \ +docker inspect localstack-aws | \ jq -r '.[0].NetworkSettings.Networks | to_entries | .[].value.IPAddress' # prints 172.27.0.2 # run your application container -docker run --rm -it --dns 172.27.0.2 --network ls +docker run --rm -it --dns 172.27.0.2 ``` @@ -234,9 +232,19 @@ Please update your LocalStack container and see the [instructions](#from-your-co LocalStack must listen to the address of the host, or `0.0.0.0`. - + +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +env = ["listen-all"] + +[env.listen-all] +GATEWAY_LISTEN = "0.0.0.0" +``` + ```bash -GATEWAY_LISTEN="0.0.0.0" localstack start +lstk start ``` diff --git a/src/content/docs/aws/customization/networking/dns-server.md b/src/content/docs/aws/customization/networking/dns-server.md index 4c77bf77f..00597aa27 100644 --- a/src/content/docs/aws/customization/networking/dns-server.md +++ b/src/content/docs/aws/customization/networking/dns-server.md @@ -130,8 +130,15 @@ Remember to save the default configuration and restore it after testing. 1. Expose the LocalStack DNS server: - a) Since version 3.5, the LocalStack CLI does not publish port `53` anymore by default. - Use the CLI flag `--host-dns` to expose the port on the host. + a) `lstk` does not publish port `53` on the host by default. + Add `expose_ports = [53]` to the container block in your `config.toml` to expose it: + + ```toml + # .lstk/config.toml + [[containers]] + type = "aws" + expose_ports = [53] + ``` b) For Docker Compose, add the following port mappings to your `docker-compose.yml`: @@ -189,6 +196,11 @@ Start LocalStack for AWS with `DNS_ADDRESS=127.0.0.1` as environment variable. This makes LocalStack bind port 53 on 127.0.0.1, whereas systemd-resolved binds its stub resolver to 127.0.0.53:53, which prevents a conflict. Once LocalStack is started, you can test the DNS server using `dig @127.0.0.1 s3.amazonaws.com` versus `dig @127.0.0.53 s3.amazonaws.com`, the former should return an A record `127.0.0.1`, the latter the real AWS DNS result. +:::caution +The `dns` command is only available in the [deprecated LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli#dns-systemd-resolved). +`lstk` has no equivalent command, so these steps require the legacy `localstack` CLI. +::: + Run: ```bash diff --git a/src/content/docs/aws/customization/networking/external-port-range.mdx b/src/content/docs/aws/customization/networking/external-port-range.mdx index 1fc870e9e..bc7b86772 100644 --- a/src/content/docs/aws/customization/networking/external-port-range.mdx +++ b/src/content/docs/aws/customization/networking/external-port-range.mdx @@ -6,8 +6,6 @@ sidebar: order: 3 --- -import { Tabs, TabItem } from '@astrojs/starlight/components'; - ## Introduction LocalStack provides local cloud services, such as [OpenSearch](/aws/services/opensearch) or [Elasticsearch](/aws/services/es), which might utilize external software bound to specific ports. @@ -41,17 +39,8 @@ By adjusting these environment variables, you can customize the port range accor If you wish to run multiple instances of LocalStack simultaneously, it is essential to ensure that the edge port (default: `4566`) and external service ports are mapped to non-overlapping ranges. -Here's how you can achieve this using when either using the CLI or docker-compose to start your LocalStack instances: +Here's how you can achieve this using docker-compose to start your LocalStack instances: - - -```bash -GATEWAY_LISTEN=0.0.0.0:4566 EXTERNAL_SERVICE_PORTS_START=4510 EXTERNAL_SERVICE_PORTS_END=4559 MAIN_CONTAINER_NAME=localstack-main-1 localstack start -GATEWAY_LISTEN=0.0.0.0:4666 EXTERNAL_SERVICE_PORTS_START=4610 EXTERNAL_SERVICE_PORTS_END=4659 MAIN_CONTAINER_NAME=localstack-main-2 localstack start -GATEWAY_LISTEN=0.0.0.0:4766 EXTERNAL_SERVICE_PORTS_START=4710 EXTERNAL_SERVICE_PORTS_END=4759 MAIN_CONTAINER_NAME=localstack-main-3 localstack start -``` - - ```yaml showshowLineNumbers services: localstack-main-1: @@ -99,9 +88,7 @@ services: - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack" - "/var/run/docker.sock:/var/run/docker.sock" ``` - - By customizing the `GATEWAY_LISTEN` and `EXTERNAL_SERVICE_PORTS_START`/`EXTERNAL_SERVICE_PORTS_END` values for each instance, you can ensure that they operate on distinct port ranges, preventing any conflicts and enabling smooth execution of multiple LocalStack instances. -Please make sure to set `MAIN_CONTAINER_NAME` for following usages of the LocalStack CLI to specify which instance of LocalStack you want to address with the specific CLI command. +Each instance is given a distinct `MAIN_CONTAINER_NAME` so that it can be addressed individually. diff --git a/src/content/docs/aws/customization/other-installations/devcontainers.mdx b/src/content/docs/aws/customization/other-installations/devcontainers.mdx index bbe67b4a2..814e53f96 100644 --- a/src/content/docs/aws/customization/other-installations/devcontainers.mdx +++ b/src/content/docs/aws/customization/other-installations/devcontainers.mdx @@ -19,6 +19,11 @@ You can use the following two approaches to set up LocalStack with DevContainers ## LocalStack Templates +:::note +The LocalStack DevContainer templates and Feature install the legacy `localstack` CLI, not the new CLI experience, `lstk`. +The commands and configuration keys on this page therefore refer to the [legacy LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/), which is what is available inside the DevContainer. +::: + LocalStack provides two different approaches for [Templates](https://github.com/localstack/devcontainer-template) which can be used via [supporting tools](https://containers.dev/supporting). | **Type** | **Advantages** | **Disadvantages** | diff --git a/src/content/docs/aws/customization/other-installations/enterprise-image.md b/src/content/docs/aws/customization/other-installations/enterprise-image.md index 1ef2bdd59..15900e62f 100644 --- a/src/content/docs/aws/customization/other-installations/enterprise-image.md +++ b/src/content/docs/aws/customization/other-installations/enterprise-image.md @@ -27,11 +27,20 @@ This offline functionality is enabled by: - After the image is pushed to the customer-specific ECR repository, the customer can pull and push it to their internal Docker registry. - Developers within the customer’s network can then pull the image from this registry. -- To use the image from the command line interface (CLI), set the `IMAGE_NAME` configuration to the name of the Enterprise image, typically using the command: +- To use the image from the command line interface (CLI), set the `image` field on the container block to the name of the Enterprise image: + ```toml + # .lstk/config.toml + [[containers]] + type = "aws" + image = "localstack-enterprise" + ``` + ```bash - IMAGE_NAME=localstack-enterprise localstack start + lstk start ``` + See [Custom container image](/aws/developer-tools/running-localstack/lstk#custom-container-image) for details, including how `lstk` falls back to a locally present image when a pull fails. + ## "Online" vs "Offline" image This section compares the standard [LocalStack for AWS Docker image](/aws/customization/other-installations/docker-images) ("online") with the customer-specific Enterprise image ("offline"). @@ -53,7 +62,7 @@ The main integrations are: - **License activation**: The standard image performs online activation using your `LOCALSTACK_AUTH_TOKEN`. See [Auth Token](/aws/getting-started/auth-token) for activation behavior and fallbacks. - **Event reporting (telemetry)**: Used for Stack Insights and related usage analytics. You can disable this via `DISABLE_EVENTS=1`. -- **Cloud Pods (platform remote)**: Saving/loading pods against the default platform remote uses LocalStack-managed infrastructure. For stricter data residency, configure your own Cloud Pods [remote storage](/aws/developer-tools/snapshots/cloud-pods#remotes). +- **Cloud Pods (platform remote)**: Saving/loading pods against the default platform remote uses LocalStack-managed infrastructure. See [Cloud Pods](/aws/developer-tools/snapshots/cloud-pods/) for where that data is held. For stricter data residency, consider other [remote storage options](/aws/developer-tools/snapshots/saving-snapshots-to-s3). - **Ephemeral instances**: These are managed cloud instances and therefore require connectivity to LocalStack Cloud services. ### Recommended setup for offline environments diff --git a/src/content/docs/aws/customization/other-installations/podman.md b/src/content/docs/aws/customization/other-installations/podman.md index e30bcf961..857442213 100644 --- a/src/content/docs/aws/customization/other-installations/podman.md +++ b/src/content/docs/aws/customization/other-installations/podman.md @@ -10,6 +10,11 @@ By default, the LocalStack CLI starts the LocalStack runtime inside a Docker con Docker may not be available on your system, and a popular alternative is [Podman](https://podman.io/get-started) which you can use to run LocalStack. Podman support is still experimental, and the following docs give you an overview of the current state. +:::note +The new CLI experience, `lstk`, does not yet fully support Podman. +The commands and environment variables on this page refer to the legacy [LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/), which you should continue to use for Podman setups. +::: + From the Podman docs: > Podman is a daemonless, open source, Linux native tool designed to make it easy to find, run, build, share and deploy applications using Open Containers Initiative (OCI) Containers and Container Images. diff --git a/src/content/docs/aws/customization/other-installations/rancher-desktop.mdx b/src/content/docs/aws/customization/other-installations/rancher-desktop.mdx index 3f0f8b3ac..631a55a06 100644 --- a/src/content/docs/aws/customization/other-installations/rancher-desktop.mdx +++ b/src/content/docs/aws/customization/other-installations/rancher-desktop.mdx @@ -16,6 +16,11 @@ It utilizes `containerd` and `dockerd`, enabling users to easily switch between By default, the LocalStack CLI launches the LocalStack runtime inside a Docker container. However, if Docker is not available on your system, you can use Rancher Desktop as a popular alternative to run LocalStack. +:::note +The new CLI experience, `lstk`, does not yet fully support Rancher Desktop. +The commands and environment variables on this page refer to the legacy [LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/), which you should continue to use for Rancher Desktop setups. +::: + ## Getting started To run LocalStack using Rancher Desktop, simply aliasing Docker commands to Rancher Desktop's `dockerd` service may not be sufficient for these reasons: diff --git a/src/content/docs/aws/developer-tools/aws-replicator/index.mdx b/src/content/docs/aws/developer-tools/aws-replicator/index.mdx index f05ff9a3a..0af4537b1 100644 --- a/src/content/docs/aws/developer-tools/aws-replicator/index.mdx +++ b/src/content/docs/aws/developer-tools/aws-replicator/index.mdx @@ -20,17 +20,14 @@ LocalStack AWS Replicator creates identical copies of AWS resources in a running This means that external resources can easily be replicated before deploying the main application, and removes the need to change existing stacks or create custom infrastructure, making LocalStack setup easier. :::note -The AWS Replicator is in a preview state, supporting only [selected resources](#supported-resources). +The AWS Replicator is in a preview state, supporting only [selected resources](#supported-resources). The new CLI experience, `lstk`, does not yet support the AWS Replicator. +Continue using the legacy [LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/) version 4.2.0 or newer. ::: ## Getting started A valid `LOCALSTACK_AUTH_TOKEN` must be configured to start the LocalStack for AWS image. -:::note -The Replicator is in limited preview and is available from LocalStack CLI version 4.2.0. -If you encounter issues, update your [LocalStack CLI](/aws/getting-started/installation/#updating-localstack-cli). -::: ### Retrieve credentials to access AWS diff --git a/src/content/docs/aws/developer-tools/chaos-engineering/chaos-api.md b/src/content/docs/aws/developer-tools/chaos-engineering/chaos-api.md index c1df187b3..c6e936d95 100644 --- a/src/content/docs/aws/developer-tools/chaos-engineering/chaos-api.md +++ b/src/content/docs/aws/developer-tools/chaos-engineering/chaos-api.md @@ -33,7 +33,7 @@ If you'd like to try it out, please [contact us](https://www.localstack.cloud/de The prerequisites for this guide are: -- LocalStack for AWS and [LocalStack CLI](/aws/getting-started/installation/) +- LocalStack for AWS and [`lstk`](/aws/developer-tools/running-localstack/lstk/#installation) - [LocalStack Auth Token](/aws/getting-started/auth-token/) - [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) - [Python](https://www.python.org/downloads/) @@ -119,7 +119,7 @@ All calls to these services in these regions will return a 503 Service Unavailab To see this in action, try to create an S3 bucket in `us-east-1`: ```bash -awslocal s3 mb s3://test-bucket --region us-east-1 +lstk aws s3 mb s3://test-bucket --region us-east-1 ``` ```bash @@ -129,7 +129,7 @@ make_bucket failed: s3://test-bucket An error occurred (ServiceUnavailableExcept However, the same operation, when run in `eu-central-1` will work as expected. ```bash -awslocal s3 mb s3://test-bucket --region eu-central-1 +lstk aws s3 mb s3://test-bucket --region eu-central-1 ``` ```bash diff --git a/src/content/docs/aws/developer-tools/cloud-sandbox/app-preview.md b/src/content/docs/aws/developer-tools/cloud-sandbox/app-preview.md index 46ecbe256..2ba963f69 100644 --- a/src/content/docs/aws/developer-tools/cloud-sandbox/app-preview.md +++ b/src/content/docs/aws/developer-tools/cloud-sandbox/app-preview.md @@ -105,7 +105,7 @@ preview-cmd: | make deploy; make build-frontend; make deploy-frontend; - distributionId=$(awslocal cloudfront list-distributions | jq -r '.DistributionList.Items[0].Id'); + distributionId=$(lstk aws cloudfront list-distributions | jq -r '.DistributionList.Items[0].Id'); echo LS_PREVIEW_URL=$AWS_ENDPOINT_URL/cloudfront/$distributionId/ >> $GITHUB_ENV; ``` diff --git a/src/content/docs/aws/developer-tools/cloud-sandbox/ephemeral-instances.md b/src/content/docs/aws/developer-tools/cloud-sandbox/ephemeral-instances.md index 1c00d0113..7de8e2a2d 100644 --- a/src/content/docs/aws/developer-tools/cloud-sandbox/ephemeral-instances.md +++ b/src/content/docs/aws/developer-tools/cloud-sandbox/ephemeral-instances.md @@ -13,7 +13,8 @@ Ephemeral Instances allows you to run a LocalStack instance in the cloud. You can interact with these instances via the LocalStack Web Application, or by configuring your integrations and developer tools with the endpoint URL of the ephemeral instance. :::note -Ephemeral Instances is offered as a **preview** feature and is under active development. +Ephemeral Instances is offered as a **preview** feature. `lstk` does not yet support Ephemeral Instances. +Continue using the legacy [LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/) for this feature. ::: ## Getting started diff --git a/src/content/docs/aws/developer-tools/lambda-tools/hot-reloading.mdx b/src/content/docs/aws/developer-tools/lambda-tools/hot-reloading.mdx index 1f07b7a6b..68e7a6351 100644 --- a/src/content/docs/aws/developer-tools/lambda-tools/hot-reloading.mdx +++ b/src/content/docs/aws/developer-tools/lambda-tools/hot-reloading.mdx @@ -142,7 +142,7 @@ To create the Lambda function, you just need to take care of two things: So, using the AWS example, this would be: ```bash -awslocal lambda create-function --function-name my-cool-local-function \ +lstk aws lambda create-function --function-name my-cool-local-function \ --code S3Bucket="hot-reload",S3Key="/tmp/aws-doc-sdk-examples/python/example_code/lambda" \ --handler lambda_handler_basic.lambda_handler \ --runtime python3.8 \ @@ -153,23 +153,12 @@ You can also check out some of our [Deployment Configuration Examples](#deployme We can also quickly make sure that it works by invoking it with a simple payload: - - ```bash -awslocal lambda invoke --function-name my-cool-local-function \ - --payload '{"action": "increment", "number": 3}' \ - output.txt -``` - - -```bash -awslocal lambda invoke --function-name my-cool-local-function \ +lstk aws lambda invoke --function-name my-cool-local-function \ --cli-binary-format raw-in-base64-out \ --payload '{"action": "increment", "number": 3}' \ output.txt ``` - - The invocation returns itself returns: @@ -332,10 +321,10 @@ To create the Lambda function, you need to take care of two things: * Set the S3 key to the path of the directory your lambda function resides in. The handler is then referenced by the filename of your lambda code and the function in that code that needs to be invoked. -Create the Lambda Function using the `awslocal` CLI: +Create the Lambda Function using `lstk aws`: ```bash -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name hello-world \ --runtime "nodejs16.x" \ --role arn:aws:iam::123456789012:role/lambda-ex \ @@ -345,25 +334,13 @@ awslocal lambda create-function \ You can quickly make sure that it works by invoking it with a simple payload: - - ```bash -awslocal lambda invoke \ - --function-name hello-world \ - --payload '{"action": "test"}' \ - output.txt -``` - - -```bash -awslocal lambda invoke \ +lstk aws lambda invoke \ --function-name hello-world \ --cli-binary-format raw-in-base64-out \ --payload '{"action": "test"}' \ output.txt ``` - - The invocation returns itself returns: @@ -422,10 +399,10 @@ This is enabled using the [`nodemon-webpack-plugin`](https://www.npmjs.com/packa ##### Creating the Lambda Function with Webpack -You can now create the Lambda function using the `awslocal` CLI: +You can now create the Lambda function using `lstk aws`: ```bash -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name localstack-example \ --runtime nodejs18.x \ --role arn:aws:iam::000000000000:role/lambda-ex \ @@ -436,7 +413,7 @@ awslocal lambda create-function \ Additionally, you can create a Lambda Function URL with the following command: ```bash -function_url=$(awslocal lambda create-function-url-config \ +function_url=$(lstk aws lambda create-function-url-config \ --function-name localstack-example \ --auth-type NONE | jq -r '.FunctionUrl') ``` @@ -629,8 +606,8 @@ LAMBDA_MOUNT_CWD=$(pwd)/build/hot serverless deploy --stage local ```bash STAGE=local && LAMBDA_MOUNT_CWD=$(pwd)/build/hot && - cdklocal bootstrap aws://000000000000/$(AWS_REGION) && \ - cdklocal deploy + lstk cdk bootstrap aws://000000000000/$(AWS_REGION) && \ + lstk cdk deploy ``` @@ -686,7 +663,7 @@ Please note that this environment variable name is arbitrary - you can use any y You can then deploy a hot-reloading function with the following command: ```bash -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name test-function \ --code S3Bucket=hot-reload,S3Key='$HOST_LAMBDA_DIR/src' \ --handler handler.handler \ diff --git a/src/content/docs/aws/developer-tools/lambda-tools/remote-debugging.mdx b/src/content/docs/aws/developer-tools/lambda-tools/remote-debugging.mdx index cad8e99c8..ee009a500 100644 --- a/src/content/docs/aws/developer-tools/lambda-tools/remote-debugging.mdx +++ b/src/content/docs/aws/developer-tools/lambda-tools/remote-debugging.mdx @@ -42,7 +42,7 @@ This guide describes how to use the AWS Toolkit for VS Code to debug Lambda func ### Prerequisites -* Upgrade to LocalStack v4.8 (or higher) for both your LocalStack CLI and your LocalStack Docker image. +* Install the [`lstk` CLI](/aws/developer-tools/running-localstack/lstk) * [VS Code](https://code.visualstudio.com/) (>= v1.83.0) * [AWS Toolkit for VS Code](https://marketplace.visualstudio.com/items?itemName=AmazonWebServices.aws-toolkit-vscode) (>= v3.74) * [LocalStack Toolkit for VS Code](https://marketplace.visualstudio.com/items?itemName=LocalStack.localstack) (>= v1.2.0) @@ -196,10 +196,19 @@ necessary tools and flexibility to troubleshoot effectively. To enable Lambda Debug Mode, set the `LAMBDA_DEBUG_MODE` environment variable as shown below: +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +env = ["lambda-debug"] + +[env.lambda-debug] +LAMBDA_DEBUG_MODE = "1" +LAMBDA_DOCKER_FLAGS = "-p 19891:19891" +``` + ```bash -LAMBDA_DEBUG_MODE=1 \ -LAMBDA_DOCKER_FLAGS='-p 19891:19891' \ -localstack start +lstk start ``` When enabled, Lambda Debug Mode automatically adjusts timeouts to accommodate debugging needs: @@ -217,11 +226,21 @@ Manually setting `LAMBDA_DOCKER_FLAGS` is unnecessary when using this configurat Here is an example of mounting a `debug_config.yaml` in your LocalStack container to start your Debug Mode: - + +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +env = ["lambda-debug-advanced"] +volumes = ["/path/to/debug-config.yaml:/tmp/lambda_debug_mode_config.yaml"] + +[env.lambda-debug-advanced] +LAMBDA_DEBUG_MODE = "1" +LAMBDA_DEBUG_MODE_CONFIG_PATH = "/tmp/debug_config.yaml" +``` + ```bash -LOCALSTACK_LAMBDA_DEBUG_MODE=1 \ -LOCALSTACK_LAMBDA_DEBUG_MODE_CONFIG_PATH=/tmp/debug_config.yaml \ -localstack start --volume /path/to/debug-config.yaml:/tmp/lambda_debug_mode_config.yaml +lstk start ``` @@ -338,8 +357,18 @@ to [iterate quickly over your function code](/aws/developer-tools/lambda-tools/h First, make sure that LocalStack is started with the following configuration (see the [Configuration docs](/aws/customization/configuration-options#lambda) for more information): +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +env = ["lambda-debug"] + +[env.lambda-debug] +LAMBDA_DOCKER_FLAGS = "-p 19891:19891" +``` + ```bash -LAMBDA_DOCKER_FLAGS='-p 19891:19891' localstack start +lstk start ``` #### Preparing your code @@ -479,7 +508,7 @@ To create the Lambda function, you just need to take care of two things: Using the AWS CLI, this would be: ```bash -awslocal lambda create-function --function-name my-cool-local-function \ +lstk aws lambda create-function --function-name my-cool-local-function \ --code S3Bucket="hot-reload",S3Key="$(pwd)/" \ --handler handler.handler \ --runtime python3.13 \ @@ -489,23 +518,12 @@ awslocal lambda create-function --function-name my-cool-local-function \ We can quickly verify that it works by invoking it with a simple payload: - - ```bash -awslocal lambda invoke --function-name my-cool-local-function \ - --payload '{"message": "Hello from LocalStack!"}' \ - output.txt -``` - - -```bash -awslocal lambda invoke --function-name my-cool-local-function \ +lstk aws lambda invoke --function-name my-cool-local-function \ --cli-binary-format raw-in-base64-out \ --payload '{"message": "Hello from LocalStack!"}' \ output.txt ``` - - ### Debugging JVM Lambda functions @@ -527,7 +545,7 @@ services: When creating your Lambda function, set the `_JAVA_OPTIONS` environment variable like so: ```bash -awslocal lambda create-function --function-name debugfunc \ +lstk aws lambda create-function --function-name debugfunc \ --zip-file fileb://java-handler.zip \ --handler myindex.handler \ --runtime java8.al2 \ @@ -688,7 +706,7 @@ exports.handler = async (event) => { Create the lambda function using: ```bash -awslocal lambda create-function --function-name func1 \ +lstk aws lambda create-function --function-name func1 \ --code S3Bucket="hot-reload",S3Key="$(pwd)/" \ --handler myindex.handler \ --runtime nodejs14.x \ @@ -700,23 +718,12 @@ Now to debug your lambda function, click on the `Debug` icon with `Attach to Remote Node.js` configuration selected, and then invoke your lambda function: - - -```bash -awslocal lambda invoke --function-name func1 \ - --payload '{"hello":"world"}' \ - output.txt -``` - - ```bash -awslocal lambda invoke --function-name func1 \ +lstk aws lambda invoke --function-name func1 \ --cli-binary-format raw-in-base64-out \ --payload '{"hello":"world"}' \ output.txt ``` - - ## Examples diff --git a/src/content/docs/aws/developer-tools/running-localstack/index.mdx b/src/content/docs/aws/developer-tools/running-localstack/index.mdx index 080d9d6cd..e12da3161 100644 --- a/src/content/docs/aws/developer-tools/running-localstack/index.mdx +++ b/src/content/docs/aws/developer-tools/running-localstack/index.mdx @@ -9,14 +9,17 @@ sidebar: import SectionCards from '../../../../../components/SectionCards.astro'; -Several tools are available to initialize, manage, and terminate the LocalStack emulator. Whether you utilize the standard LocalStack CLI, the next-generation `lstk` CLI, or the MCP server for AI-driven management, these interfaces provide complete control over the lifecycle of your local cloud environment. +Several tools are available to install, start, and manage the LocalStack emulator. Your starting point should be `lstk`, the modern CLI for managing LocalStack. The MCP server is also available for AI-driven management, giving you complete control over the lifecycle of your local cloud environment. + +Note that the previous `localstack` CLI is now deprecated, but can [still be used](/aws/developer-tools/running-localstack/localstack-cli/) if necessary. diff --git a/src/content/docs/aws/developer-tools/running-localstack/localstack-cli.md b/src/content/docs/aws/developer-tools/running-localstack/localstack-cli.md index 184fac030..296953166 100644 --- a/src/content/docs/aws/developer-tools/running-localstack/localstack-cli.md +++ b/src/content/docs/aws/developer-tools/running-localstack/localstack-cli.md @@ -1,6 +1,6 @@ --- -title: LocalStack CLI -description: Reference guide for LocalStack CLI commands, options, and usage. +title: Deprecated LocalStack CLI +description: Reference guide for the deprecated LocalStack CLI commands, options, and usage. We recommend using lstk instead. template: doc sidebar: order: 10 diff --git a/src/content/docs/aws/developer-tools/running-localstack/lstk.mdx b/src/content/docs/aws/developer-tools/running-localstack/lstk.mdx index 1287d737c..6c31864a8 100644 --- a/src/content/docs/aws/developer-tools/running-localstack/lstk.mdx +++ b/src/content/docs/aws/developer-tools/running-localstack/lstk.mdx @@ -22,6 +22,10 @@ Running `lstk` with no arguments takes you through the entire startup flow autom `lstk` supports core lifecycle commands (`start`, `stop`, `restart`, `logs`, `status`) along with state management via snapshots (`snapshot save`/`snapshot load`, `reset`) and an AWS CLI proxy (`lstk aws`). ::: +:::tip[Recommended] +`lstk` is the recommended way to run and manage LocalStack. The [legacy LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/) is deprecated. +::: + ## Prerequisites - [Docker](https://docs.docker.com/get-docker/) installed and running. diff --git a/src/content/docs/aws/developer-tools/running-localstack/mcp-server.mdx b/src/content/docs/aws/developer-tools/running-localstack/mcp-server.mdx index 87feb6797..a23e4efbf 100644 --- a/src/content/docs/aws/developer-tools/running-localstack/mcp-server.mdx +++ b/src/content/docs/aws/developer-tools/running-localstack/mcp-server.mdx @@ -22,6 +22,10 @@ Before configuring the MCP server, ensure the following are installed and availa - [`cdklocal`](https://github.com/localstack/aws-cdk-local), [`tflocal`](https://github.com/localstack/terraform-local), or [`samlocal`](https://github.com/localstack/aws-sam-cli-local) if you plan to use the infrastructure deployment tool. (**optional**) - [Snowflake CLI](https://docs.snowflake.com/en/developer-guide/snowflake-cli/index) (`snow`) if you plan to use the Snowflake client tool. (**optional**) +:::note +The MCP server currently manages LocalStack via the legacy `localstack` CLI and the `awslocal`, `cdklocal`, `tflocal`, and `samlocal` wrapper scripts. `lstk` support is not yet available for the MCP server. +::: + ## Installation The LocalStack MCP Server is published on npm as [`@localstack/localstack-mcp-server`](https://www.npmjs.com/package/@localstack/localstack-mcp-server). diff --git a/src/content/docs/aws/developer-tools/security-testing/custom-tls-certificates.mdx b/src/content/docs/aws/developer-tools/security-testing/custom-tls-certificates.mdx index c4813cdc6..583cb7f7c 100644 --- a/src/content/docs/aws/developer-tools/security-testing/custom-tls-certificates.mdx +++ b/src/content/docs/aws/developer-tools/security-testing/custom-tls-certificates.mdx @@ -30,7 +30,7 @@ They all can be summarised as: ## Creating a custom docker image -If you run LocalStack in a docker container (which includes using [the CLI](/aws/getting-started/installation/#installing-localstack-cli), [docker](/aws/getting-started/installation/#docker), [docker-compose](/aws/getting-started/installation/#docker-compose), or [helm](/aws/customization/kubernetes/deploy-helm-chart)), to include a custom TLS root certificate a new docker image should be created. +If you run LocalStack in a docker container (which includes using [`lstk`](/aws/developer-tools/running-localstack/lstk/), [docker](/aws/getting-started/installation/#docker), [docker-compose](/aws/getting-started/installation/#docker-compose), or [helm](/aws/customization/kubernetes/deploy-helm-chart)), to include a custom TLS root certificate a new docker image should be created. Create a `Dockerfile` containing the following commands: @@ -63,9 +63,16 @@ LocalStack now needs to be configured to use this custom image. The workflow is different depending on how you start localstack. - + +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +image = "" +``` + ```bash -IMAGE_NAME= localstack start +lstk start ``` @@ -112,8 +119,18 @@ and follow the instructions fn the [init hooks documentation](/aws/customization If your proxy intercepts traffic to LocalStack cloud services (e.g., license server), you can disable TLS verification for these specific requests using the `SSL_NO_VERIFY` [configuration variable](/aws/customization/configuration-options#security) (or `LOCALSTACK_SSL_NO_VERIFY` in Docker). +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +env = ["tls"] + +[env.tls] +SSL_NO_VERIFY = "1" +``` + ```bash -SSL_NO_VERIFY=1 localstack start +lstk start ``` :::caution diff --git a/src/content/docs/aws/developer-tools/security-testing/explainable-iam.md b/src/content/docs/aws/developer-tools/security-testing/explainable-iam.md index cc2509a76..15529efe5 100644 --- a/src/content/docs/aws/developer-tools/security-testing/explainable-iam.md +++ b/src/content/docs/aws/developer-tools/security-testing/explainable-iam.md @@ -14,12 +14,23 @@ You can enable `DEBUG=1` to gain visibility into these log messages, allowing yo ## Getting started -This guide is designed for users new to Explainable IAM and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Explainable IAM and assumes basic knowledge of the AWS CLI and our [`lstk aws` AWS CLI proxy](/aws/developer-tools/running-localstack/lstk#aws). Start your LocalStack container with the `DEBUG=1` and `ENFORCE_IAM=1` environment variables set: +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +env = ["iam-enforcement"] + +[env.iam-enforcement] +DEBUG = "1" +ENFORCE_IAM = "1" +``` + ```bash -DEBUG=1 ENFORCE_IAM=1 localstack start +lstk start ``` In this guide, we will create a policy for creating Lambda functions by only allowing the `lambda:CreateFunction` permission. @@ -46,7 +57,7 @@ Create a policy document named `policy_1.json` and add the following content: You can now create a new user named `test-user`, and put the policy in place by executing the following commands: ```bash -awslocal iam create-user --user-name test-user +lstk aws iam create-user --user-name test-user ``` ```bash @@ -62,13 +73,13 @@ awslocal iam create-user --user-name test-user ``` ```bash -awslocal iam put-user-policy --user-name test-user --policy-name policy1 --policy-document file://policy_1.json +lstk aws iam put-user-policy --user-name test-user --policy-name policy1 --policy-document file://policy_1.json ``` You can further create an access key for the user by executing the following command: ```bash -awslocal iam create-access-key --user-name test-user +lstk aws iam create-access-key --user-name test-user ``` Export the access key and secret key as environment variables: @@ -83,7 +94,7 @@ export AWS_SECRET_ACCESS_KEY=... You can now attempt to create a Lambda function using the newly created user's credentials: ```bash -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name test-function \ --role arn:aws:iam::000000000000:role/lambda-role \ --runtime python3.8 \ diff --git a/src/content/docs/aws/developer-tools/security-testing/iam-policy-enforcement.md b/src/content/docs/aws/developer-tools/security-testing/iam-policy-enforcement.md index 17e21d24f..85fd8ad86 100644 --- a/src/content/docs/aws/developer-tools/security-testing/iam-policy-enforcement.md +++ b/src/content/docs/aws/developer-tools/security-testing/iam-policy-enforcement.md @@ -15,12 +15,23 @@ Per default, IAM enforcement is disabled, and all APIs can be accessed without a ## Getting started -This guide is designed for users new to IAM Policy Enforcement and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to IAM Policy Enforcement and assumes basic knowledge of the AWS CLI and our `lstk aws` AWS CLI proxy. Start your LocalStack container with the `DEBUG=1` and `ENFORCE_IAM=1` environment variables set: +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +env = ["iam-enforcement"] + +[env.iam-enforcement] +DEBUG = "1" +ENFORCE_IAM = "1" +``` + ```bash -DEBUG=1 ENFORCE_IAM=1 localstack start +lstk start ``` We will demonstrate IAM Policy Enforcement, by creating a user and obtaining the access/secret keys. @@ -36,7 +47,7 @@ This way, we can demonstrate the differentiation in access permissions between t In **Terminal 1**, execute the following commands to create a `test` user and obtain the access/secret keys: ```bash -awslocal iam create-user --user-name test +lstk aws iam create-user --user-name test ``` ```bash @@ -52,7 +63,7 @@ awslocal iam create-user --user-name test ``` ```bash -awslocal iam create-access-key --user-name test +lstk aws iam create-access-key --user-name test ``` ```bash @@ -74,7 +85,7 @@ Once the access keys are set, you will attempt to create an S3 bucket using thes ```bash export AWS_ACCESS_KEY_ID=LKIAQAAAAAAAHFR7QTN3 AWS_SECRET_ACCESS_KEY=EYUHpIol7bRJpKd/28c/LI2C4bbEnp82LJCRwXRV -awslocal s3 mb s3://mybucket +lstk aws s3 mb s3://mybucket ``` ```bash @@ -94,8 +105,8 @@ You can view the LocalStack logs to validate the policy enforcement: Let's now return to **Terminal 1** and execute the following commands to attach a policy to the user `test`: ```bash -awslocal iam create-policy --policy-name p1 --policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"s3:CreateBucket","Resource":"*"}]}' -awslocal iam attach-user-policy --user-name test --policy-arn arn:aws:iam::000000000000:policy/p1 +lstk aws iam create-policy --policy-name p1 --policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"s3:CreateBucket","Resource":"*"}]}' +lstk aws iam attach-user-policy --user-name test --policy-arn arn:aws:iam::000000000000:policy/p1 ``` ### Create a bucket @@ -103,7 +114,7 @@ awslocal iam attach-user-policy --user-name test --policy-arn arn:aws:iam::00000 Now, let's switch back to **Terminal 2** and observe how the bucket creation succeeds with the `test` IAM user: ```bash -awslocal s3 mb s3://mybucket +lstk aws s3 mb s3://mybucket ``` ```bash diff --git a/src/content/docs/aws/developer-tools/security-testing/iam-policy-stream.md b/src/content/docs/aws/developer-tools/security-testing/iam-policy-stream.md index f1ae1f199..8f06dd3b2 100644 --- a/src/content/docs/aws/developer-tools/security-testing/iam-policy-stream.md +++ b/src/content/docs/aws/developer-tools/security-testing/iam-policy-stream.md @@ -16,13 +16,14 @@ Subsequently, it displays the suggested policy. This feature aids in identifying the correct permissions for cloud applications and can help spot logical errors, such as unexpected actions in a policy. :::note -IAM Policy Stream is offered as a **preview** feature and is under active development. +IAM Policy Stream is offered as a **preview** feature and is under active development. `lstk` does not yet support IAM Policy Stream. +Continue using the legacy [LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/) for this feature. ::: ## Getting started This guide is designed for users who are new to the IAM Policy Stream. -It assumes you have basic knowledge of the AWS CLI (and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script). +It assumes you have basic knowledge of the AWS CLI (and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk#aws) AWS CLI proxy). ### Start your LocalStack container @@ -52,7 +53,7 @@ In a separate terminal tab, we will create AWS resources to observe the necessar In this example, we are creating an SNS topic using the following command: ```bash -awslocal sns create-topic --name test-topic +lstk aws sns create-topic --name test-topic ``` In the other tab, the required policy will be generated. @@ -97,7 +98,7 @@ To use this feature, open the LocalStack Web Application in your browser, go to Run the following command in your terminal to generate a corresponding policy in the IAM Policy Stream dashboard: ```bash -awslocal sns create-topic --name test-topic +lstk aws sns create-topic --name test-topic ``` You will see the following output in the IAM Policy Stream dashboard: diff --git a/src/content/docs/aws/developer-tools/snapshots/cli-commands.md b/src/content/docs/aws/developer-tools/snapshots/cli-commands.md deleted file mode 100644 index 7959df783..000000000 --- a/src/content/docs/aws/developer-tools/snapshots/cli-commands.md +++ /dev/null @@ -1,416 +0,0 @@ ---- -title: CLI commands -description: Reference guide for LocalStack Cloud Pods CLI commands and how to get started on using them. -template: doc -tags: ["Ultimate"] -sidebar: - order: 6 ---- - -This reference provides descriptions and example commands for LocalStack Cloud Pods CLI (`pod`) commands. - -## Syntax - -Use the following syntax to run `localstack pod` commands from your terminal window: - -```bash -localstack pod [OPTIONS] COMMAND [ARGS]... -``` - -In the above syntax: -- `COMMAND` specifies the operation you want to perform with your Cloud Pods (`save` or `load`). -- `OPTIONS` specifies the optional flags. -- `ARGS` specifies the command arguments. - -## Commands - -The following section lists the available commands for the Cloud Pods CLI. -You can have an overview of these command by typing `localstack pod --help`: - -```bash -Usage: pod [OPTIONS] COMMAND [ARGS]... - - Manage the state of your instance via Cloud Pods. - -Options: - --help Show this message and exit. - -Commands: - delete Delete a Cloud Pod - inspect Inspect the contents of a Cloud Pod This command shows the... - list List all available Cloud Pods - load Load the state of a Cloud Pod into the application runtime/... - remote Manage cloud pod remotes - save Create a new Cloud Pod - versions List all available versions for a Cloud Pod This command lists... -``` - -### `save` - -```bash -Usage: pod save [OPTIONS] NAME [REMOTE] - - Save the current state of the LocalStack container in a Cloud Pod. - - A Cloud Pod can be registered and saved with different storage options, - called remotes. - By default, Cloud Pods are hosted in the LocalStack - platform. - However, users can decide to store their Cloud Pods in other - remotes, such as AWS S3 buckets or ORAS registries. - - An optional message can be attached to any Cloud Pod. - Furthermore, one - could decide to export only a subset of services with the optional - --service option. - - To use the LocalStack platform for storage, the desired Cloud Pod's name will suffice, e.g.: - - localstack pod save - - Please be aware that each following save invocation with the same name - will result in a new version being created. - - To save a local copy of your state, you can use the 'localstack state export' command. - -Options: - -m, --message TEXT Add a comment describing this Cloud Pod's - version - - -s, --services TEXT Comma-delimited list of services to push in - the Cloud Pod (all by default) - - --visibility [public|private] Set the visibility of the Cloud Pod [`public` - or `private`]. - Does not create a new version - - -S, --secret TEXT Secret for the Cloud Pod encryption. Encryption is an - Enterprise only feature. - - -f, --format [json] The formatting style for the save command - output. - - --help Show this message and exit. -``` - -The `save` command allows you to save a new version of a Cloud Pod targeting a specific remote. -To save and load the state locally, you can use the command in the `localstack state` group. - -```bash -localstack pod save my-pod -``` - -The above command generates a new version of `my-pod` and uploads it on the LocalStack platform. -When pushing an already existing pod, a new version is created and subsequently uploaded to the platform. - -Users also have the option to select a specific subset of AWS services they want to include in the new Cloud Pod version using the `--services` option. - -Users who want to make a Cloud Pod accessible outside their organization can mark it as **public** with the following command: - -```bash -localstack pod save --name my-pod --visibility public -``` - -The above command does not create a new version and requires a version already registered with the platform. -The CLI manual for the `save` command is as follows: - -### `load` - -```bash -Usage: pod load [OPTIONS] NAME [REMOTE] - - Load the state of a Cloud Pod into the application runtime/ Users can - import Cloud Pods from different remotes, with the LocalStack platform - being the default one. - - Loading the state of a Cloud Pod into LocalStack might cause some - conflicts with the current state of the container. - By default, LocalStack - will attempt a best-effort merging strategy between the current state and - the one from the Cloud Pod. - For a service X present in both the current - state and the Cloud Pod, we will attempt to merge states across different - accounts and regions. - If the service X has a state for the same account - and region both in the running container and the Cloud Pod, the latter - will be used. - If a service Y is present in the running container but not - in the Cloud Pod, it will be left untouched. - With `--merge overwrite`, the - state of the Cloud Pod will completely replace the state of the running - container. - - To load a local copy of a LocalStack state, you can use the 'localstack state import' command. - -Options: - --merge [overwrite|merge] The merge strategy to adopt when loading the - Cloud Pod - - -y, --yes Automatic yes to prompts. - Assume a positive - answer to all prompts and run non-interactively - - --help Show this message and exit. -``` - -The `load` command is the inverse operation of `save`. -It retrieves the content of a previously stored Cloud Pod a remote (by default, theLocalStack platform) and injects it into the LocalStack container. - -### `delete` - -```bash -Usage: pod delete [OPTIONS] NAME - - Delete a Cloud Pod registered on the remote LocalStack platform. - - This command will remove all the versions of a Cloud Pod, and the - operation is not reversible. - -Options: - --help Show this message and exit. -``` - -The `delete` command let users delete a Cloud Pod stored in the remote platform. -The CLI manual for the `delete` command is as follows: - -### `inspect` - -```bash -Usage: pod inspect [OPTIONS] NAME - - Inspect the contents of a Cloud Pod - - This command shows the content of a Cloud Pod. - By default, it starts a - curses interface which allows an interactive inspection of the contents in - the Cloud Pod. - -Options: - -f, --format [curses|rich|json] - The formatting style for the inspect command - output. - - --help Show this message and exit. -``` - -The `inspect` command simply lets the user inspect the content of a Cloud Pod. - -### `list` - -```bash -Usage: pod list [OPTIONS] [REMOTE] - - List all the Cloud Pods available for a single user, or for an entire - organization, if the user is part of one. - - With the --public flag, it lists the all the available public Cloud Pods. - A public Cloud Pod is available across the boundary of a user one/or - organization. - In other words, any public Cloud Pod can be injected by any - other user holding a LocalStack for AWS license. - -Options: - -p, --public List all the available public Cloud Pods - -f, --format [table|json] The formatting style for the list pods command - output. - - --help Show this message and exit. -``` - -The `list` command lists all of the available Cloud Pods. -It shows all the pods available for a single user and its organization by default. - -### `versions` - -```bash -Usage: pod versions [OPTIONS] NAME - - List all available versions for a Cloud Pod - - This command lists the versions available for a Cloud Pod. - Each invocation - of the save command is going to create a new version for a named Cloud - Pod, if a Pod with such name already does exist in the LocalStack - platform. - -Options: - -f, --format [table|json] The formatting style for the version command - output. - - --help Show this message and exit. -``` - -The `versions` command lists all the available versions of a Cloud Pod. -The CLI manual for the `version` command is as follows: - -### `remote` - -The `remote` command group lets you manage custom Cloud Pod remotes, to enable alternative storage backends in addition to the default LocalStack managed platform. -It offers 3 commands: `add`, `delete`, and `list`. - -For more info about remote usage, check our [documentation](/aws/developer-tools/snapshots/cloud-pods/#remotes). - -```bash -Usage: pod remote [OPTIONS] COMMAND [ARGS]... - - Manage cloud pod remotes - -Options: - --help Show this message and exit. - -Commands: - add Add a remote - delete Delete a remote - list Lists the available remotes -``` - -#### `remote add` - -```bash -Usage: pod remote add [OPTIONS] NAME URL - - Add a new remote for Cloud Pods. - - A remote is the place where your Cloud Pods are stored. - By default, Cloud - Pods are store in the LocalStack platform. - -Options: - --help Show this message and exit. -``` - -#### `remote delete` - -```bash -Usage: pod remote delete [OPTIONS] NAME - - Remove a remote for Cloud Pods. - -Options: - --help Show this message and exit. -``` - -#### `remote list` - -```bash -Usage: pod remote list [OPTIONS] - -Options: - -f, --format [table|json] The formatting style for the remotes command - output. - - --help Show this message and exit. -``` - ---- - -# Local Commands - -In addition to the commands in the `pod` group, we also offer a simple alternative to save and load the LocalStack state. -The `state` group offers two commands to export and import the state of the LocalStack container to/from a zip file from the host machine. - -## `state` syntax - -```bash -Usage: state [OPTIONS] COMMAND [ARGS]... - - (Preview) Manage and manipulate the localstack state. - - The state command group allows you to interact with LocalStack's state - backend. - - Read more: https://docs.localstack.cloud/aws/developer-tools/snapshots/persistence/ - -Options: - --help Show this message and exit. - -Commands: - export Export the state of LocalStack services - import Import the state of LocalStack services - reset Reset the state of LocalStack services -``` - -### `state export` - -```bash -Usage: state export [OPTIONS] [DESTINATION] - - Save the current state of the LocalStack container to a file on the local - disk. - This file can be restored at any point in time using the `localstack - state import` command. - Please be aware that this might not be possible - when importing the state with a different version of LocalStack. - - If you are looking for a managed solution to handle the state of your - LocalStack container, please check out the Cloud Pods feature: - https://docs.localstack.cloud/aws/developer-tools/snapshots/cloud-pods/ - - Use the DESTINATION argument to specify an absolute path for the exported - file or a filename in current working directory. - If no destination is - specified, a file named `ls-state-export` will be saved in the current - working directory. - - Examples: - localstack state export my-state - localstack state export /home/johndoe/my-state - - You can also specify a subset of services to export. - By default, the state - of all running services is exported. - -Options: - -s, --services TEXT Comma-delimited list of services to reset. -By default, - the state of all running services is exported. - - -f, --format [json] The formatting style for the save command output. - --help Show this message and exit. -``` - -### `state import` - -```bash -Usage: state import [OPTIONS] SOURCE - - Load the state of LocalStack from a file into the running container. - The - SOURCE file must have been generated from a previous `localstack state - export` command. - Please be aware that it might not be possible to import a - state generated from a different version of LocalStack. - - Examples: - localstack state import my-state - localstack state import /home/johndoe/my-state - -Options: - --help Show this message and exit. -``` - -### `state reset` - -```bash -Usage: state reset [OPTIONS] - - Reset the service states of the current LocalStack runtime. - - This command invokes a reset of services in the currently running - LocalStack container. - By default, all services are rest. - The `services` - options allows to select a subset of services which should be reset. - - This command tries to automatically discover the running LocalStack - instance. - If LocalStack has not been started with `localstack start` (and - is not automatically discoverable), please set `LOCALSTACK_HOST`. - -Options: - -s, --services TEXT Comma-delimited list of services to reset. -By default, - the state of all running services is reset. - - --help Show this message and exit. -``` \ No newline at end of file diff --git a/src/content/docs/aws/developer-tools/snapshots/cloud-pods.mdx b/src/content/docs/aws/developer-tools/snapshots/cloud-pods.mdx index db2ea2da5..709ec2394 100644 --- a/src/content/docs/aws/developer-tools/snapshots/cloud-pods.mdx +++ b/src/content/docs/aws/developer-tools/snapshots/cloud-pods.mdx @@ -1,302 +1,325 @@ --- -title: Cloud Pods -description: Get started with Cloud Pods to manage the state of your LocalStack instance state. +title: Saving snapshots to Cloud Pods +description: Using LocalStack's Cloud Pods repository to share snapshots with your team. template: doc tags: ["Base"] sidebar: - order: 2 + order: 3 --- -import { Tabs, TabItem, FileTree } from '@astrojs/starlight/components'; -import { Badge } from '@astrojs/starlight/components'; +import { Tabs, TabItem } from '@astrojs/starlight/components'; -## Introduction +In [the previous section](/aws/developer-tools/snapshots/saving-snapshots-locally/) you learned how to save a snapshot of the emulator's state to a local file, +then reload the snapshot into a different emulator instance. When working in a team environment, it's important to have a standard mechanism for sharing +snapshot files among your team, and for managing updates when new versions are published. -Cloud pods are persistent state snapshots of your LocalStack instance that can easily be stored, versioned, shared, and restored. -Cloud Pods can be used for various purposes, such as: +
+ Cloud Pods workflows +
-- Save and manage snapshots of active LocalStack instances. -- Share state snapshots with your team to debug collectively. -- Automate your testing pipelines by pre-seeding CI environments. -- Create reproducible development and testing environments locally. +LocalStack provides the web-based _Cloud Pods_ repository for exactly this purpose, accessible only to the users in your organization. Snapshots are +generated by an emulator instance, then automatically published to your Cloud Pods repository. From there, snapshots can be loaded +back into an instance, either in a desktop environment or a CI environment. -![Cloud Pods Web UI](/images/aws/pods-ui.png) +
+ Cloud Pods Web UI +
-## Installation +Each organization has its own private Cloud Pods repository, securely managed in LocalStack's cloud. These repositories are backed by dedicated, +isolated Amazon S3 buckets. 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's Platform APIs. -You can save and load the persistent state of Cloud Pods, you can use the [Cloud Pods command-line interface (CLI)](/aws/developer-tools/snapshots/cli-commands). -LocalStack provides a remote storage backend that can be used to store the state of your running application and share it with your team members. -You can interact with the Cloud Pods over the storage backend via the LocalStack Web Application. +:::note[Data residency] +Cloud Pods are stored on LocalStack-managed infrastructure in the AWS `eu-central-1` region. This is the only part of the LocalStack platform that +retains your data long-term. If your organization requires snapshots to remain within infrastructure you control, save them to +[your own S3 bucket](/aws/developer-tools/snapshots/saving-snapshots-to-s3/) instead. +::: -Cloud Pods CLI is included in the [LocalStack CLI installation](/aws/getting-started/installation/#installing-localstack-cli), so there's no need for additional installations to begin using it. -If you're a licensed user, we suggest setting the `LOCALSTACK_AUTH_TOKEN` as an environment variable. -This enables you to access the complete range of LocalStack Cloud Pods features. +## Using the `lstk` CLI -You can access the Cloud Pods CLI by running the `pod` command from your terminal. +You can save and load snapshots to or from your Cloud Pods repository using the [`lstk snapshot`](/aws/developer-tools/running-localstack/lstk/#snapshot) command. ```bash -localstack pod --help +lstk snapshot --help ``` -```bash -Usage: localstack pod [OPTIONS] COMMAND [ARGS]... - Manage the state of your instance via Cloud Pods. -Options: - -h, --help Show this message and exit. +```bash title="Output" +Manage emulator snapshots + +Usage: lstk snapshot [flags] Commands: - delete Delete a Cloud Pod - inspect - list List all available Cloud Pods - load - remote Manage cloud pod remotes - save Create a new Cloud Pod - versions -``` + 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 + versions List the version history of a cloud snapshot -:::note -These Cloud Pods are securely stored within an AWS storage backend, where each user or organization is allocated a dedicated and isolated S3 bucket. -The LocalStack Cloud Pods CLI utilizes secure S3 presigned URLs to directly interface with the S3 bucket, bypassing the need to transmit the state files through LocalStack Platform APIs. -::: +Options: + -h, --help help for snapshot -## Getting started +Global Options: + --config string Path to config file + --endpoint-url string Target an existing, externally-managed emulator at this URL + --json Output in JSON format (only supported by some commands) + --non-interactive Disable interactive mode +``` -This guide is designed for users new to Cloud Pods and assumes basic knowledge of the LocalStack CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +### Saving a snapshot to Cloud Pods -Start your LocalStack container using your preferred method. -We will demonstrate how you can save a snapshot of your active LocalStack instance into your LocalStack account, and pull it to a running instance. +The following examples build up a Cloud Pod over three versions, adding one service at a time. +Start an emulator instance and create a single S3 bucket: -### Create AWS resources +```bash +lstk start +lstk aws s3 mb s3://bucket1 +``` -You can use the `awslocal` CLI to create new AWS resources within your active LocalStack instance. -For example, you can create an S3 bucket and add data to it using the `awslocal` CLI: +The command for saving a snapshot to Cloud Pods is similar to the one for saving locally, but instead of a file name, provide the `pod:` prefix followed by a valid Cloud Pod name. ```bash -awslocal s3 mb s3://test -echo "hello world" > /tmp/hello-world -awslocal s3 cp /tmp/hello-world s3://test/hello-world -awslocal s3 ls s3://test/ +lstk snapshot save pod:sample-application ``` -### Save your Cloud Pod state +```bash title="Output" +✔︎ Snapshot saved to pod:sample-application +• Version: 1 +• Services: s3 +• Size: 64.2 KB +``` -You can now save your Pod state using the `save` command, specifying the desired Cloud Pod name as the first argument. -This action will save the pod and register it with the LocalStack Web Application: +You can list the available Cloud Pods, for both you and your organization, using the `lstk snapshot list` command: ```bash -localstack pod save s3-test +lstk snapshot list ``` -```bash -Cloud Pod `s3-test` successfully created ✅ -Version: 1 -Remote: platform -Services: s3 -``` +```bash title="Output" +~ 1 snapshot -Optionally, you can include a message with the saved Cloud Pod using the `--message` flag. + NAME VERSION LAST CHANGED + sample-application 1 2026-08-04 01:00 UTC +``` -You can access the list of available Cloud Pods for both you and your organization by utilizing the `list` command: +With the `save` command, you can create multiple versions of a Cloud Pod. +For instance, to create an SQS queue and save a second version of `sample-application`: ```bash -localstack pod list +lstk aws sqs create-queue --queue-name queue-1 +lstk snapshot save pod:sample-application ``` -```bash -┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓ -┃ Name ┃ Max Version ┃ Last Change ┃ -┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩ -│ s3-test │ 1 │ 2024-01-04 11:03:00 │ -└──────────────────────────────┴─────────────┴─────────────────────┘ +```bash title="Output" +✔︎ Snapshot saved to pod:sample-application +• Version: 2 +• Services: sqs, s3 +• Size: 76.0 KB ``` -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`. +Adding an SNS topic and saving once more produces a third version: ```bash -awslocal sqs create-queue --queue-name test-queue - -localstack pod save s3-test +lstk aws sns create-topic --name topic1 +lstk snapshot save pod:sample-application ``` -```bash -Cloud Pod `s3-test` successfully created ✅ -Version: 2 -Remote: platform -Services: s3,sqs +```bash title="Output" +✔︎ Snapshot saved to pod:sample-application +• Version: 3 +• Services: sqs, sns, s3 +• Size: 85.4 KB ``` -We can now use the command `versions` to list all the created version for a Cloud Pod. +To review the version history of a Cloud Pod, use the `versions` command. +Note how each version covers the services that existed in the emulator at the time it was saved: ```bash -localstack pod versions s3-test +lstk snapshot versions pod:sample-application ``` -```bash -┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓ -┃ Version ┃ Creation Date ┃ LocalStack Version ┃ Services ┃ Description ┃ -┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩ -│ 1 │ 2024-01-04 11:03:00 │ 3.1.1. │ s3 │ │ -│ 2 │ 2024-02-28 14:01:45 │ 3.1.1. │ s3,sqs │ │ -└─────────┴─────────────────────┴─────────────────────────┴──────────┴─────────────┘ +```bash title="Output" +~ 3 versions + + VERSION CREATED LOCALSTACK SERVICES + 3 2026-08-04 01:01 UTC 2026.8.0 sqs, sns, s3 + 2 2026-08-04 01:00 UTC 2026.8.0 sqs, s3 + 1 2026-08-04 01:00 UTC 2026.8.0 s3 ``` -### Pull your Pod state +:::note +Permissions on Cloud Pods are assigned at the organization level. +This means that every individual in the organization can view, load, and delete snapshots created by other team members. +Similarly, everyone can save a new version on top of a snapshot originally created by someone else. +::: -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: +### Loading snapshots from a Cloud Pod + +To load a snapshot from a Cloud Pod into a running emulator, use the `lstk snapshot load` command: ```bash -localstack pod load s3-test +lstk restart +lstk snapshot load pod:sample-application ``` -```bash -Cloud Pod s3-test successfully loaded +```bash title="Output" +✔︎ Snapshot loaded from pod:sample-application +• Services: s3, sns, sqs ``` -You can examine the S3 buckets within the Cloud Pod: +You can examine the loaded resources with the `lstk status` command: ```bash -awslocal s3 ls s3://test/ +lstk status ``` -```bash -2022-10-04 22:33:54 12 hello-world +```bash title="Output" +✔︎ LocalStack AWS Emulator is running +• Endpoint: localhost.localstack.cloud:4566 +• Container: localstack-aws-dev +• Version: 2026.8.0 +• Uptime: 59s +~ 3 resources · 3 services + SERVICE RESOURCE REGION ACCOUNT + S3 bucket1 global 000000000000 + SNS topic1 us-east-1 000000000000 + SQS http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/queue-1 us-east-1 000000000000 ``` -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. +By default, `load` fetches the most recent version of the Cloud Pod. To work with an earlier version, append `:` to the +Cloud Pod name. Before loading, you can inspect the metadata for a specific version with the `show` command: + ```bash -localstack pod load s3-test:1 +lstk snapshot show pod:sample-application:1 ``` -```bash -Cloud Pod s3-test:1 successfully loaded +```bash title="Output" +Name sample-application +Version 1 +Created 2026-08-04 01:00 UTC +Size 64.2 KB +LocalStack 2026.8.0 + +Services s3 ``` -After loading the Cloud Pod's content, you can use the `state inspect` command to observe the state of the running LocalStack instance. +As expected, version 1 covers only S3, since the SQS queue and SNS topic were created later. +To load this older version into the running emulator, use the same `:` suffix with the `load` command: ```bash -localstack state inspect --format json +lstk restart +lstk snapshot load pod:sample-application:1 ``` -```bash -{ - "000000000000": { - "S3": { - "global": { - "listBuckets": { - "Buckets": [ - { - "Name": "test", - "CreationDate": "2023-10-03T07:19:31.000Z" - } - ], - } - } - } - } -} +```bash title="Output" +✔︎ Snapshot loaded from pod:sample-application:1 +• Services: s3 ``` -For comprehensive instructions, navigate to our [Command-Line Interface (CLI) Guide](/aws/developer-tools/snapshots/cli-commands/). -To access your Cloud Pods through the LocalStack Web Application, navigate to the [Cloud Pods browser](https://app.localstack.cloud/pods). +Comprehensive instructions on using the `lstk snapshot` CLI command are found in the [`lstk` CLI Guide](/aws/developer-tools/running-localstack/lstk/#snapshot). :::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. +The snapshots stored in a Cloud Pod may not remain compatible if used with a different version of LocalStack. +LocalStack applies [snapshot compatibility rules](/aws/developer-tools/snapshots/service-coverage#snapshot-compatibility) to block loading snapshots known to be incompatible with the running LocalStack version. ::: -## Web Application +## Using the LocalStack Console -The LocalStack Web Application enables you to : +The LocalStack Console 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 your Cloud Pods and access your snapshot version history. +- Save and load snapshots to and from Cloud Pods. +- View snapshot metadata, resources, regions, and version history. ### Browse Cloud Pods -[Cloud Pods Browser](https://app.localstack.cloud/pods) 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](https://app.localstack.cloud/pods) allows you to view, manage, and explore your snapshots through the LocalStack Console. +With Cloud Pods, you can have individual or shared ownership of snapshots. -![LocalStack Web Application's Cloud Pods Browser outlining various saved Clod Pods" title="Cloud Pods Browser](/images/aws/cloud-pods-browser.png) +![LocalStack Web Application's Cloud Pods Browser outlining various saved snapshots](/images/aws/cloud-pods-browser.png "Cloud Pods Browser") -The Cloud Pods Browser provides the following functionalities: +The Cloud Pods Browser provides the following functionality: -- **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**: View all snapshots saved by you or your organization. +- **View Versions**: View the version history of a Cloud Pod and access previous snapshots by clicking on the Cloud Pod's name. +- **View Snapshot Details**: View the details of a specific version by clicking on the version number. +- **View Cloud Pod Storage**: View both the organization-wide and user-specific storage usage. +- **Delete Cloud Pod**: Delete a Cloud Pod by selecting the name and navigating to the **Actions** button, followed by **Delete**. -### View Cloud Pods metadata +### View snapshot metadata -You can view Cloud Pods metadata by selecting any Cloud Pod in the [Cloud Pods Browser](https://app.localstack.cloud/pods). +You can view snapshot metadata by selecting any snapshot in the [Cloud Pods Browser](https://app.localstack.cloud/pods). The metadata includes details such as: -- The user who created the Cloud Pod +- The user who created the snapshot - 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. +- The LocalStack version used to create the snapshot +- The size of the snapshot +- The service resources contained in the snapshot -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. +You can view detailed information within a snapshot, including available resources, categorized services with configurations, and quick access to resource identifiers and endpoints—all without loading the snapshot into your LocalStack runtime. ![Cloud Pods details](/images/aws/cloud-pod-details.png) -### Export & Import Cloud Pods +:::note +To save a snapshot with enhanced detail for each of the resources, start your LocalStack instance with the `ENABLE_POD_RESOURCES=1` option. +::: + +### Save and load snapshots to or from 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. +You can save and load snapshots using the LocalStack Console. This is useful when you prefer a user-friendly interface without the need to interact with the CLI. -![LocalStack Export/Import State Cloud Pod Mode](/images/aws/export-import-state-cloud-pod.png) +![LocalStack Save/Load Snapshot Cloud Pod Mode](/images/aws/export-import-state-cloud-pod.png) -#### Export the State +#### Save the snapshot -To export the state, follow these steps: +To save a snapshot, follow these steps: -1. Navigate to the **Cloud Pod** tab within the [Export/Import State](https://app.localstack.cloud/inst/default/state) page. +1. Navigate to the **Cloud** tab within the [State](https://app.localstack.cloud/inst/default/state) page. 2. Create AWS resources locally as needed. -3. Enter the Pod name and toggle between the **New Pod** and **Existing Pod** options. +3. Enter the Cloud 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](https://app.localstack.cloud/pods) page. +A new Cloud Pod will be created, or an existing Cloud Pod will be updated. The snapshot is immediately available for loading into another LocalStack instance. +You can view the list of available Cloud Pods on the [Cloud Pods](https://app.localstack.cloud/pods) page. -#### Import the State +#### Load the snapshot -To import the state, follow these steps: +To load a snapshot, follow these steps: -1. Navigate to the **Cloud Pod** tab within the [Export/Import State](https://app.localstack.cloud/inst/default/state) page. -2. Choose the Cloud Pod from the drop-down list. +1. Navigate to the **Cloud** tab within the [State](https://app.localstack.cloud/inst/default/state) page. +2. Choose the relevant 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](https://app.localstack.cloud/inst/default/resources) 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. +## Auto-loading from Cloud Pods -### Environmental variables +In addition to loading snapshots through the Command-Line Interface (CLI) or the Console, you can configure the automatic loading of one or more Cloud Pods upon the startup of the LocalStack instance. -To automatically load a Cloud Pod at startup, utilize the `AUTO_LOAD_POD` [configuration variable](/aws/customization/configuration-options/). +The recommended way to automatically load a snapshot from a Cloud Pod at startup is to set the `snapshot` field in your `lstk` [`config.toml`](/aws/developer-tools/running-localstack/lstk/#auto-loading-a-snapshot-on-start). +However, if you run the LocalStack container directly, for example via Docker Compose or `docker run`, you can instead use the `AUTO_LOAD_POD` [configuration variable](/aws/customization/configuration-options/). `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. - + +Set the `snapshot` field on the container block in your [`config.toml`](/aws/developer-tools/running-localstack/lstk/#auto-loading-a-snapshot-on-start) to the Cloud Pod's `pod:` REF: + +```toml +[[containers]] +type = "aws" +port = "4566" +snapshot = "pod:foo-pod" +``` + ```bash -AUTO_LOAD_POD=foo-pod localstack start +lstk start ``` @@ -329,433 +352,3 @@ docker run \ -### 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 -- init-pods.d - - pod-list.txt - - my-state.pod.zip - - -The `pod-list.txt` contains the following: - -```text -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: - -```yaml showLineNumbers -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" -``` - -## Remotes - -A remote is the location where Cloud Pods are stored. -By default, Cloud Pod artifacts are stored in the LocalStack platform. -However, if your organization's data regulations or sovereignty requirements prohibit storing Cloud Pod assets in a remote storage infrastructure, you have the option to persist Cloud Pods in an on-premises storage location under your complete control. - -LocalStack provides two types of alternative remotes: - -- S3 bucket remote storage. -- [ORAS](https://oras.land/) (OCI Registry as Storage) remote storage. - -Cloud Pods command-line interface (CLI) allows you to create, delete, and list remotes. - -```bash -localstack pod remote --help -``` - -```bash -Usage: localstack pod remote [OPTIONS] COMMAND [ARGS]... - - Manage cloud pod remotes - -Options: - -h, --help Show this message and exit. - -Commands: - add Add a remote - delete Delete a remote - list List the available remotes -``` - -### S3 bucket remote storage - -The S3 remote enables you to store Cloud Pod assets in an existing S3 bucket within an actual AWS account. -The initial step is to export the necessary AWS credentials within the terminal session. - -```bash -export AWS_ACCESS_KEY_ID=... -export AWS_SECRET_ACCESS_KEY=... -``` - -A possible option is to obtain credentials via [AWS SSO CLI](https://github.com/synfinatic/aws-sso-cli). - -:::note -**LocalStack v2026.08 or later:** Cloud Pods can be saved to and loaded from real AWS S3 buckets while [Transparent Endpoint Injection](/aws/customization/networking/transparent-endpoint-injection/) is enabled (the default configuration). - -**LocalStack versions before v2026.08:** If you encounter TLS certificate validation errors when saving Cloud Pods to a real S3 bucket, disable the DNS server by setting `DNS_ADDRESS=0` and restart LocalStack. -This workaround disables transparent endpoint injection application-wide. -For more details, see [DNS Server configuration](/aws/customization/networking/dns-server/#dns-server-bind-address). -::: - -Next, we establish a new remote specifically designed for an S3 bucket. -By running the following command, we create a remote named `s3-storage-aws` responsible for storing Cloud Pod artifacts in an S3 bucket called `ls-pods-bucket-test`. - -The `access_key_id` and `secret_access_key` placeholders ensure the correct transmission of AWS credentials to the container. - -```bash -localstack pod remote add s3-storage-aws 's3://ls-pods-bucket-test/?access_key_id={access_key_id}&secret_access_key={secret_access_key}' -``` - -Lastly, you can utilize the standard `pod` CLI command to generate a new Cloud Pod that points to the previously established remote. - -```bash -localstack pod save my-pod s3-storage-aws -``` - -Once the command has been executed, you can confirm the presence of Cloud Pod artifacts in the S3 bucket by simply running: - -```bash -aws s3 ls s3://ls-pods-bucket-test -2023-09-27 13:50:10 83650 localstack-pod-my-pod-state-1.zip -2023-09-27 13:50:11 85103 localstack-pod-my-pod-version-1.zip -``` - -You can use the `pod load` command to load the same pod that was previously saved in this remote: - -```bash -localstack pod load my-pod s3-storage-aws -``` - -Similarly, you can list the Cloud Pods on this specific remote with the `pod list` command: - -```bash -localstack pod list s3-storage-aws -``` - -:::note -Full S3 remotes support is available in the CLI from version 3.2.0. -If you experience any difficulties, update your [LocalStack CLI](/aws/getting-started/installation/#updating-localstack-cli). -::: - -### ORAS remote storage - -The ORAS remote enables users to store Cloud Pods in OCI-compatible registries like Docker Hub, Nexus, or ECS registries. -ORAS stands for "OCI Registry as Service," and you can find additional information about this standard [on the official website](https://oras.land/). - -For example, let's illustrate how you can utilize Docker Hub to store and retrieve Cloud Pods. - -To begin, you must configure the new remote using the LocalStack CLI. -You'll need to export two essential environment variables, `ORAS_USERNAME` and `ORAS_PASSWORD`, which are necessary for authenticating with Docker Hub. - -```bash -export ORAS_USERNAME=docker_hub_id -export ORAS_PASSWORD=ILoveLocalStack1! -``` - -You can now use the CLI to create a new remote called `oras-remote`. - -```bash -localstack pod remote add oras-remote 'oras://{oras_username}:{oras_password}@registry.hub.docker.com/' -``` - -Lastly, you can store a pod using the newly configured remote, where `my-pod` represents the Cloud Pod's name, and `oras-remote` is the remote's name. - -```bash -localstack pod save my-pod oras-remote -``` - -Likewise, you can execute the reverse operation to load a Cloud Pod from `oras-remote` using the following command: - -```bash -localstack pod load my-pod oras-remote -``` - -### Auto Load with remotes - -LocalStack also supports the auto load of a Cloud Pod from registered remotes. -The configuration is similar to what we just described. -In particular you could simply add the remote name to the text files inside the `init-pods.d`, as follows: - -```text -foo-pod,bar-remote -``` - -With such a configuration, the `foo-pod` Cloud Pod will be loaded from the `bar-remote` remote. -To properly configure the remote, you need to provide the needed environment variables when starting the LocalStack container. -For instance, a S3 remote needs a `AWS_ACCESS_KEY` and a `AWS_SECRET_ACCESS_KEY`, as follows: - -```yaml showLineNumbers -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 - - AWS_ACCESS_KEY_ID:... - - AWS_SECRET_ACCESS_KEY:... - volumes: - - "./volume:/var/lib/localstack" - - "./init-pods.d:/etc/localstack/init-pods.d" -``` - -:::note -The Auto Load from remote feature does not automatically configure the remote. -This needs to be done with the `localstack pod remote add ...` command. -This commands creates a configuration file for the remote in the [LocalStack volume directory](/aws/customization/advanced/filesystem/#localstack-volume-directory). -::: - -## End-to-End Encryption - -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.: - -```bash -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. - -```bash -localstack pod save my-secret-pod --secret 3X03eU5pgoejObUR+Y8I4QjbjeGEKjDcmVFd0FU5pCg= -``` - -Loading an encrypted Cloud Pod would require a similar `load` command: - -```bash -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. - -### Miscellaneous - -Unless explicitly specified, all Cloud Pods commands default to targeting the LocalStack Platform as the storage remote. -It's important to note that the CLI must be authenticated correctly with our Platform. - -Custom remote configurations are stored within the [LocalStack volume directory](/aws/customization/advanced/filesystem/#localstack-volume-directory) and are managed by the LocalStack container. -Consequently, when sharing Cloud Pods among your team using a custom remote, each team member must define the identical remote configuration. -Once added, a remote persists even after LocalStack restarts. - -## State Merging - -Cloud Pods offers various strategies for integrating states into your LocalStack container. -The available strategies are: - -- `overwrite`: This strategy clears the existing state and loads the new state from the Cloud Pod, completely resetting the LocalStack state. -- `account-region-merge` (**default**): This strategy merges services based on account and region pairs. - It attempts to combine states from both the current state and the Cloud Pod for the same account and region. -- `service-merge`: This strategy merges services at the account-region level, provided there's no overlap in resources. - It prioritizes the loaded resources when merging. - -The LocalStack's default merge strategy can be changed via the `MERGE_STRATEGY` [configuration variable](/aws/customization/configuration-options/). - -### LocalStack CLI - -Every `pod load` operation uses the merge strategy set in `MERGE_STRATEGY` (`account-region-merge` by default). -When loading a Cloud Pod via the LocalStack CLI, set the `--strategy ` option to override the strategy in the configuration variable. -For instance, to load a Cloud Pod named `test-pod-s3-sqs` with the `service-merge` strategy, run the following command: - -```bash -localstack pod load test-pod-s3-sqs --strategy service-merge -``` - -### LocalStack Web Application - -To activate merge strategies, navigate to the **Cloud Pods** tab on the [Export/Import State page](https://app.localstack.cloud/inst/default/state). -Enter the name of the Cloud Pod, select the version, choose the strategy from a dropdown, and click **Load State from Pod**. - -![Merge Strategy Web UI](/images/aws/merge-strategy-web-app.png) - -### Example scenario - -Let us take the image below as example. -The two non overlapping account/region pairs (`0123456789/us-east-1` for the Cloud Pod and `0123456789/us-east-2` for the runtime) will be both present in the resulting state. -For `0123456789/eu-central-1` however, we encounter a conflict, since both the Cloud Pod and the container hold a SQS state. -With the `account-region-merge` strategy, the one from the Cloud Pod will be preserved. - -![Merge Strategies](/images/aws/merge-strategies.png) - -On the other hand, in the `service-merge` strategy, the SQS resulting state will have 2 distinct queues if the queue from the Cloud Pod and the one in the container are distinct, i.e., do not have the same ARN. -In case of an ARN conflict, only one queue, the one from the Cloud Pod, will be present in the result. - -### Dry Run - -To preview the changes that would occur when loading a Cloud Pod, you can use the `--dry-run` flag. -The result will depend on the selected merge strategy. -The result will be displayed in the console, and no changes will be made to the LocalStack state. - -```bash -This load operation will modify the runtime state as follows: - -──────────────────────────── sns ──────────────────────────── -+ 2 resources added. -~ 1 resources modified. - -──────────────────────── cognito-idp ──────────────────────── -+ 1 resources added. -~ 0 resources modified. - -──────────────────────────── sqs ──────────────────────────── -+ 1 resources added. -~ 1 resources modified. -``` - -## Cloud Pods & Persistence - -[Persistence](/aws/developer-tools/snapshots/persistence) ensures that the service state persists across container restarts. -You can enable persistence via a LocalStack config flag `PERSISTENCE=1` to restore your local resources, in case you’re stopping and re-starting the LocalStack instance on the same machine. - -In contrast, Cloud Pods provide more detailed control over your state. -Rather than just restoring a state during LocalStack restarts, Cloud Pods enable you to capture snapshots of your local instance using the `save` command and inject these snapshots into a running instance using the `load` command, all without needing to perform a full restart. - -### Current Limitations - -Cloud Pods (and state management in general), come with a few limitation. -In particular, Cloud Pods states might not be correctly restored if the LocalStack version used to create the pod and the target one differ. -We detect version miss-matches when using the `pod load` and prompt a confirmation message to the user. - -```bash -localstack pod load old-pod -``` - -```bash -This Cloud Pod was created with LocalStack 2.1.0. -but you are running LocalStack 3.2.1. -Cloud Pods might be incompatible across different LocalStack versions. -Loading a Cloud Pod with mismatching version might lead to a corrupted state of the emulator. -Do you want to continue? [y/N]: -``` - -In addition to this prompt, Cloud Pods are subject to the [state compatibility rules](/aws/developer-tools/snapshots/persistence#state-compatibility) shared with snapshot-based persistence. -Pods that were saved before `v2026.03` cannot be loaded into LocalStack `v2026.03` or later, because persistence was rewritten for several services in that release. -Set `DISABLE_COMPATIBILITY_RULES=1` to bypass the checks at your own risk. - -We are working to extend Cloud Pods support to all AWS services emulated in LocalStack. -However, state management might not yet work reliably for every service. - -## Troubleshooting - -### Unable to obtain Auth Token - -When you try to save a Cloud Pod and see the error in LocalStack logs like this: - -```bash -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 `` 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: - -```bash -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: - -```bash -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: - -```bash -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: - -```bash -export AWS_SESSION_TOKEN=... -``` - -Then, add `session_token` to the `pod remote add` URL: - -```bash -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: - -```bash -DNS_NAME_PATTERNS_TO_RESOLVE_UPSTREAM=ls-pods-bucket-test.s3.amazonaws.com/ -``` - -For more details, see the [Skip LocalStack DNS Resolution](/aws/customization/networking/dns-server/#skip-localstack-dns-resolution) section. diff --git a/src/content/docs/aws/developer-tools/snapshots/export-import-state.md b/src/content/docs/aws/developer-tools/snapshots/export-import-state.md deleted file mode 100644 index 2b8a726c0..000000000 --- a/src/content/docs/aws/developer-tools/snapshots/export-import-state.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Export & Import State -description: Export and import the state of the current infrastructure state into a file or a LocalStack instance respectively. -template: doc -tags: ["Base"] -sidebar: - order: 4 ---- - -## Introduction - -The Export/Import State feature enables you to export the state of your LocalStack instance into a file and import it into another LocalStack instance. -This feature is useful when you want to save your LocalStack instance's state for later use. - -## LocalStack CLI - -The LocalStack CLI enables you to export your infrastructure state to a file and import it into another LocalStack instance. -You can access the state management commands by running `localstack state` in your terminal. - -```bash -localstack state --help -``` - -```bash -Usage: localstack state [OPTIONS] COMMAND [ARGS]... - - (Preview) Manage and manipulate the localstack state. - - The state command group allows you to interact with LocalStack's state - backend. - - Read more: https://docs.localstack.cloud/references/persistence- - mechanism/#snapshot-based-persistence - -Options: - -h, --help Show this message and exit. - -Commands: - export Export the state of LocalStack services - import Import the state of LocalStack services - reset Reset the state of LocalStack services -``` - -### Export the State - -To export the state, you can run the following command: - -```bash -localstack state export -``` - -You can specify a file path to export the state to. -If you do not specify a file path, the state will be exported to the current working directory into a file named `ls-state-export`. -You can specify the following flags to customize the export: - -- `--services`: Specify the services to export. - You can specify multiple services by separating them with a comma. - If you do not specify any services, all services will be exported. -- `--format`: Specify the format of the exported state. - For example, you can specify `json` to specify the save command output as JSON. - -### Import the State - -To import the state, you can run the following command: - -```bash -localstack state import -``` - -The `` argument is required and specifies the file path to import the state from. -The file should be generated from a previous export. - -## Web Application - -The LocalStack Web Application enables you to export your infrastructure state to a file and import it into another LocalStack instance. -The Local mode allows you to perform local exports and imports of your LocalStack instance's state. - -![LocalStack Export/Import State Local Mode](/images/aws/export-import-state-local.png) - -### Export the State - -To export the state, follow these steps: - -1. Navigate to the **Local** tab within the [Export/Import State](https://app.localstack.cloud/inst/default/state) page. -2. Create AWS resources locally as needed. -3. Click on the **Export State** button. - This action will initiate the download of a ZIP file. - -The downloaded ZIP file contains your container state, which can be injected into another LocalStack instance for further use. - -### Import the State - -To import the state, follow these steps: - -1. Navigate to the **Local** tab within the [Export/Import State](https://app.localstack.cloud/inst/default/state) page. -2. Upload the ZIP file that contains your container state. - This action will restore your previously loaded AWS resources. - -To confirm the successful injection of the container state, visit the respective [Resource Browser](https://app.localstack.cloud/inst/default/resources) for the services and verify the resources. \ No newline at end of file diff --git a/src/content/docs/aws/developer-tools/snapshots/index.md b/src/content/docs/aws/developer-tools/snapshots/index.md deleted file mode 100644 index bbcc54ec6..000000000 --- a/src/content/docs/aws/developer-tools/snapshots/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Overview -description: State Management in LocalStack allows you to save and load the state of your LocalStack instance. -template: doc -sidebar: - order: 1 ---- - -LocalStack is designed to be ephemeral by default, meaning all state is lost when the container stops. State Management gives you tools to persist, reuse, and share the state of your LocalStack instance across sessions or teams. This is useful for preloading test data, debugging workflows, or collaborating with teammates. - -LocalStack supports three ways to manage and reuse state: - -* [**Cloud Pods**](/aws/developer-tools/snapshots/cloud-pods): Shareable, versioned snapshots of your LocalStack instance that can be stored, restored, and synced via the LocalStack platform. - -* [**Export & Import State**](/aws/developer-tools/snapshots/export-import-state): Save your instance state to a local file and reload it manually as needed. - -* [**Persistence**](/aws/developer-tools/snapshots/persistence): Automatically save and reload state locally by enabling a configuration flag. - -Internally, all three approaches manage the same container state. They just differ in how the state is stored and reused (local vs remote, manual vs automated). - -The diagram below helps compare these options at a glance. - -![The difference between persistence, local state and Cloud Pods.](/images/aws/persistence-pods-remote.png) - diff --git a/src/content/docs/aws/developer-tools/snapshots/index.mdx b/src/content/docs/aws/developer-tools/snapshots/index.mdx new file mode 100644 index 000000000..5412588e6 --- /dev/null +++ b/src/content/docs/aws/developer-tools/snapshots/index.mdx @@ -0,0 +1,69 @@ +--- +title: Overview +description: Snapshots in LocalStack allow you to save and load the state of your LocalStack instance. +template: doc +sidebar: + order: 1 +--- + +import { SectionCards } from '../../../../../components/SectionCards.tsx'; + +LocalStack is designed to be ephemeral by default, meaning all state is lost when the container stops. The _Snapshot_ feature provides tools to persist, reuse, and share the state of your LocalStack instance across sessions or teams. This is useful for preloading test data, debugging workflows, or collaborating with teammates. + +
+ Overview of the LocalStack snapshot lifecycle +
+ +Snapshots enhance your development workflow in the following ways: + +* **Faster loading** - Snapshots can be loaded into your instance within a few seconds. Use this to avoid lengthy redeploys of your infrastructure as code, such as Terraform or CDK, each time the emulator is started. + +* **Team sharing** - Use a repository, such as _Cloud Pods_, to share snapshots with your team. Snapshots provide a curated set of resources for team members to use as a starting point for their work. + +* **Automatic durability** - Enable the _Persistence_ feature to gain the same durability semantics you expect from the AWS cloud. A snapshot is taken automatically when the instance is shut down, or at user-defined intervals during operation, then reloaded when the instance is restarted. + +* **Application preview** - During the code review process, share a snapshot so reviewers can see the software in action without redeploying it for themselves. + +* **Debugging failures** - Save the state of an instance after a failure has occurred to allow debugging at a later time or by a different team member. + +For more detail, see the following sections: + + + +:::caution +Not all LocalStack services support snapshots. If you encounter a limitation, please [contact support](/aws/help-support/get-help/). +::: \ No newline at end of file diff --git a/src/content/docs/aws/developer-tools/snapshots/launchpad.md b/src/content/docs/aws/developer-tools/snapshots/launchpad.md deleted file mode 100644 index 4e0177a4b..000000000 --- a/src/content/docs/aws/developer-tools/snapshots/launchpad.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Launchpad -description: Get started with Cloud Pods Launchpad to share and inject Cloud Pods into your LocalStack instance via a URL. -template: doc -tags: ["Ultimate"] -sidebar: - order: 5 ---- - -The LocalStack Cloud Pods Launchpad enables you to easily share and inject Cloud Pods into a LocalStack instance. - -## Creating your shareable link - -You can visit [Cloud Pods launchpad](https://app.localstack.cloud/launchpad) to generate a shareable link for your pods. - -![Cloud Pods Launchpad Link Generator](/images/aws/link-generator.png) - -Enter a public URL to your pod Cloud Pod the first input field, then click **Generate Link**. -You can copy the resulting link and share it with others. -Additionally, you have the option to copy a markdown snippet for quickly adding a badge to your repository. - -:::danger -The Launchpad accepts any URL as input and directly passes it to your LocalStack instance for Cloud Pod injection. -As a result, this process may carry the risk of unintended side effects, as there is no validation applied to the URL provided to the launchpad. - -Furthermore, it's essential to exercise caution and only use URLs that you trust when utilizing the launchpad, as the URL is displayed in the user interface. -::: - -## Adding a badge to your repository - -To add a badge to your README that links to the Cloud Pod Launchpad, you can include the following markdown snippet: - -```markdown -[![Launch LocalStack Cloudpod](https://localstack.cloud/gh/launch-pod-badge.svg)](https://app.localstack.cloud/launchpad?url=url_of_your_pod) -``` - -![Cloud Pods Badge Demonstration](/images/aws/badge-demo.png) - -You need to include the `url_of_your_pod` as the `url` query parameter in the URL. -For instance, if your Cloud Pod is hosted within the same repository, simply use the URL that directs to the raw Cloud Pod file. - -Additionally, you can utilize the [Link Generator](#creating-your-shareable-link) to generate a shareable link for your pod and copy the corresponding markdown snippet for your repository. -Check out a proper example on th Cloud Pod badge GitHub repository. - -## Troubleshooting common problems - -In this section we present an overview of common problems and how to solve them. - -### LocalStack is not running - -If your LocalStack instance is not running, you will encounter the following error message: - -![Cloud Pods Launchpad Error LocalStack not running](/images/aws/ls-not-running.png) - -Start your LocalStack instance and attempt the operation once more. -For detailed instructions on starting LocalStack, refer to the [Getting Started](/aws/getting-started/) section. - -### Failed to load metadata - -If the launchpad encounters difficulties while loading the metadata of your pod, you will receive the following error message: - -![Cloud Pods Launchpad Error failed to load metadata](/images/aws/metadata-load-failed.png) - -This can occur when the pod is no longer accessible or if the URL provided is invalid. -Review the URL and attempt the operation once more. - -### Failed to inject pod - -If the launchpad is unable to successfully inject the pod into your LocalStack instance, you will encounter a `Pod injection failed` message in the log. -This issue may arise from various factors, such as version disparities. -For further insights and information, please review your LocalStack logs. \ No newline at end of file diff --git a/src/content/docs/aws/developer-tools/snapshots/merging-snapshots.md b/src/content/docs/aws/developer-tools/snapshots/merging-snapshots.md new file mode 100644 index 000000000..dcb06c8ca --- /dev/null +++ b/src/content/docs/aws/developer-tools/snapshots/merging-snapshots.md @@ -0,0 +1,96 @@ +--- +title: Merging snapshots +description: Merge strategies for loading multiple snapshots into the same emulator instance. +template: doc +tags: ["Base"] +sidebar: + order: 5 +--- + +LocalStack's snapshot mechanism allows multiple snapshot files to be merged into the same emulator instance. +This is useful when several teams collaborate to build a single running emulator image. + +For example, a Platform team may create a snapshot containing VPCs, subnets, S3 buckets, and SSM parameters. An Application team then produces their own snapshot (building on the first) containing Lambda functions, S3 buckets, ECS images, and other application-level resources. It's therefore important to load multiple snapshots, one on top of the other. + +LocalStack supports several _merge strategies_ for loading a snapshot into an existing emulator instance. You can think of this as loading two or more snapshots into the same emulator instance, one after the other. + +The chosen strategy can be passed to `lstk snapshot load` either by using the `--merge` option, or by setting the `LSTK_MERGE_STRATEGY` environment variable. + +```bash +lstk snapshot load --merge= +LSTK_MERGE_STRATEGY= lstk snapshot load +``` + +## `overwrite` strategy + +This strategy completely resets the state of the instance before loading each new snapshot. This results in the instance containing the new snapshot's content, with resources from the older snapshot being discarded. + +![Merging snapshots using `--merge=overwrite`](/images/aws/snapshot-merge-overwrite.png) + +For this merge strategy, use the following: + +```bash +lstk snapshot load snapshot1 +lstk snapshot load --merge=overwrite snapshot2 +lstk status +``` + +```bash title="Output" + [...] + SNS topic3 us-east-1 000000000000 + SQS http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/queue-3 us-east-1 000000000000 +``` + +## `account-region-merge` strategy (**default**) + +This strategy merges snapshots at the service level, for any given account and region. For example, if the first snapshot contains an SQS queue (`queue-1`) in the `000000000000/us-east-1` account and region, and the second snapshot contains a different SQS queue (`queue-3`), also in the `000000000000/us-east-1` account and region, the first snapshot's SQS resources are discarded. This strategy does not consider whether the SQS queues have different names, since _all_ SQS resources in that account/region are discarded. + +![Merging snapshots using `--merge=account-region-merge`](/images/aws/snapshot-merge-account-region.png) + +For this merge strategy, use the following: + +```bash +lstk snapshot load snapshot1 +lstk snapshot load --merge=account-region-merge snapshot2 +lstk status +``` + +```bash title="Output" + [...] + S3 bucket1 global 000000000000 + SNS topic2 ap-southeast-2 000000000000 + SNS topic3 us-east-1 000000000000 + SQS http://sqs.ap-southeast-2.localhost.localstack.cloud:4566/000000000000/queue-2 ap-southeast-2 000000000000 + SQS http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/queue-3 us-east-1 000000000000 +``` + +## `service-merge` strategy + +This strategy performs fine-grained merging, similar to the `account-region-merge` strategy, but also considers the names of resources. For example, if each snapshot contains an SQS queue, but the queues have different names (`queue-1` vs `queue-3`), the merge contains both queues. If the names are the same, the resource from the newer snapshot is kept. + +This is the same behavior you'd expect if you applied two infrastructure-as-code stacks, one on top of the other. + +![Merging snapshots using `--merge=service-merge`](/images/aws/snapshot-merge-service.png) + +For this merge strategy, use the following: + +```bash +lstk snapshot load snapshot1 +lstk snapshot load --merge=service-merge snapshot2 +lstk status +``` + +```bash title="Output" + [...] + S3 bucket1 global 000000000000 + SNS topic1 us-east-1 000000000000 + SNS topic2 ap-southeast-2 000000000000 + SNS topic3 us-east-1 000000000000 + SQS http://sqs.ap-southeast-2.localhost.localstack.cloud:4566/000000000000/queue-2 ap-southeast-2 000000000000 + SQS http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/queue-1 us-east-1 000000000000 + SQS http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/queue-3 us-east-1 000000000000 +``` + +:::note +Merge strategies are not currently supported for file-based snapshots when using the LocalStack Console. +::: diff --git a/src/content/docs/aws/developer-tools/snapshots/persistence.mdx b/src/content/docs/aws/developer-tools/snapshots/persistence.mdx index f68558d4d..dd4e26ef4 100644 --- a/src/content/docs/aws/developer-tools/snapshots/persistence.mdx +++ b/src/content/docs/aws/developer-tools/snapshots/persistence.mdx @@ -1,35 +1,34 @@ --- title: Persistence -description: Internals of LocalStack persistence mechanism. +description: Enabling automatic persistence of data, providing enhanced durability. template: doc sidebar: - order: 3 + order: 6 tags: ["Base"] --- -import { Tabs, TabItem, FileTree } from '@astrojs/starlight/components'; +import { Tabs, TabItem } from '@astrojs/starlight/components'; -## Introduction - -LocalStack's Persistence mechanism enables the saving and restoration of the entire LocalStack state, including all AWS resources and data, on your local machine. -It functions as a "pause and resume" feature, allowing you to take a snapshot of your LocalStack instance and save this data to disk. -This mechanism ensures a quick and efficient way to preserve and continue your work with AWS resources locally. +LocalStack's _Persistence_ mechanism uses snapshots to provide an enhanced level of durability, bringing it closer to the behavior you'd expect from a cloud-based service. +By default, LocalStack's internal state is ephemeral, resetting when the emulator is shut down or exits unexpectedly. When the Persistence feature is enabled, +LocalStack takes periodic snapshots of your emulator, then restores it upon restart. This reduces the likelihood of unexpected data loss. ## Configuration -To start snapshot-based persistence, launch LocalStack with the configuration option `PERSISTENCE=1`. -This setting instructs LocalStack to save all AWS resources and their respective application states into the LocalStack Volume Directory. -Upon restarting LocalStack, you'll be able to resume your activities exactly where you left off. +To start snapshot-based persistence, launch LocalStack with the `--persist` command-line option, or the configuration option `PERSISTENCE=1`. +This instructs LocalStack to periodically generate a snapshot, storing it within LocalStack's internal volume directory. There is no visible +snapshot file (or Cloud Pod) created, as the snapshot is managed internally by LocalStack. + +Upon restarting LocalStack, the last successful snapshot is automatically reloaded, so you can resume your activities exactly where you left off. ```bash -LOCALSTACK_AUTH_TOKEN=... -PERSISTENCE=1 localstack start +lstk start --persist ``` -```yaml showshowLineNumbers +```yaml showLineNumbers image: localstack/localstack-pro environment: - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} @@ -38,7 +37,7 @@ volumes: - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack" ``` - + ```bash docker run \ -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \ @@ -51,44 +50,43 @@ docker run \ :::note -Snapshots may not be compatible across different versions of LocalStack. -LocalStack applies [state compatibility rules](#state-compatibility) that block loading state files known to be incompatible with the running LocalStack version. +Snapshots (stored in LocalStack's volume) may not remain compatible if you upgrade your version of LocalStack. +LocalStack applies [snapshot compatibility rules](/aws/developer-tools/snapshots/service-coverage#snapshot-compatibility) to block loading snapshots known to be incompatible with the running LocalStack version. ::: ### Save strategies -LocalStack takes point-in-time snapshot of its state and dumps them to disk. -There are four strategies that you can choose from that govern when these snapshots are taken. +LocalStack generates periodic snapshots of the running emulator. There are four strategies you can choose from to govern when these snapshots are taken. You can select a particular save strategy by setting `SNAPSHOT_SAVE_STRATEGY=`. -* **`ON_REQUEST`**: On every AWS API call that potentially modifies the state of a service, LocalStack will save the state of that service. - This strategy minimizes the chance for data loss, but also has significant performance implications. - The service has to be locked during snapshotting, meaning that any requests to the particular AWS service will be blocked until the snapshot is complete. - In many cases this is just a few milliseconds, but can become significant in some services. -* **`ON_SHUTDOWN`**: The state of all services are saved during the shutdown phase of LocalStack. - This strategy has zero performance impact, but is not good when you want to minimize the chance for data loss. - Should LocalStack for some reason not shut down properly or is terminated before it can finalize the snapshot, you may be left with an incomplete state on disk. -* **`SCHEDULED`** (**default**): Saves at regular intervals the state of all the services that have been modified since the last snapshot. +* **`ON_REQUEST`**: On every AWS API call that potentially makes a modification, LocalStack saves the state of that service. + This strategy minimizes the chance of data loss, but also has significant performance implications. + The service must be locked during snapshotting, with any requests to the particular AWS service being blocked until the snapshot is complete. + In many cases this is just a few milliseconds, but can become significant in some services. +* **`ON_SHUTDOWN`**: The state of all services is saved during the shutdown phase of LocalStack. + This strategy has negligible performance impact, but is not good for minimizing the chance of data loss. + Should LocalStack for some reason not shut down properly, or be terminated before it can finalize the snapshot, you may be left with an incomplete state on disk. +* **`SCHEDULED`** (**default**): Saves the state of all services at regular intervals, as long as the state has been modified since the last snapshot. By default, the flush interval is 15 seconds. It can be configured via the `SNAPSHOT_FLUSH_INTERVAL` configuration variable. This is a compromise between `ON_REQUEST` and `ON_SHUTDOWN` in terms of performance and reliability. * **`MANUAL`**: Turns off automatic snapshotting and gives you control through the internal state endpoints. -### Load Strategies +### Load strategies Similarly, you can configure when LocalStack should restore the state snapshots, by using `SNAPSHOT_LOAD_STRATEGY=`. -* **`ON_REQUEST`**: (**default**) The state is loaded lazily when the service is requested. +* **`ON_REQUEST`**: (**default**) The state is loaded lazily when the service is first used (that is, the first API call to that service). This maintains LocalStack's lazy-loading behavior for AWS services. -* **`ON_STARTUP`**: The state of all services in the snapshot is restored when LocalStack starts up. - This means that services that have stored state are also started on LocalStack start, which will increase the startup time, but also give you immediate feedback whether the state was restored correctly. +* **`ON_STARTUP`**: The state of all services in the snapshot is restored when LocalStack starts up, before any of the services are accessed. This + reduces the cost of lazy-loading when the data is eventually accessed, but does cause an upfront delay to pre-load everything. * **`MANUAL`**: Turns off automatic loading of snapshots and gives you control through the internal state endpoints. ### Endpoints -As mentioned, with the `MANUAL` save or load strategy you can trigger snapshotting manually when it best suits your application flow. +With the `MANUAL` save or load strategy, you can trigger snapshotting manually when it best suits your application flow. -* `POST /_localstack/state//save` take a snapshot the given service +* `POST /_localstack/state//save` take a snapshot of the given service * `POST /_localstack/state//load` load the most recent snapshot of the given service For example, a snapshot for a particular service (e.g., `s3`) can be triggered by running the following command. @@ -104,133 +102,13 @@ We provide the following endpoints: * `POST /_localstack/state/save` * `POST /_localstack/state/load` -The response streams line by line the service that has been saved/loaded and the status of the operation. +The response is a service-by-service JSON stream, showing the service that has been saved/loaded and the status of the operation. ```bash curl -X POST localhost:4566/_localstack/state/save ``` -```bash +```bash title="Output" {"service": "sqs", "status": "ok"} {"service": "s3", "status": "ok"} ``` - -## State compatibility - -The internal state format of LocalStack changes over time as services evolve. -To prevent silently loading state into an incompatible runtime, LocalStack ships a set of compatibility rules that compare the LocalStack version recorded in the saved state with the version of the running container. -The same rules apply to both [snapshot-based persistence](#configuration) and [Cloud Pods](/aws/developer-tools/snapshots/cloud-pods). - -If a rule rejects the state, LocalStack does not load it and logs the reason. -The rules currently enforced are: - -| Rule | Behavior | -| - | - | -| Forward compatibility | Reject loading a state into a LocalStack version older than the one that produced it. | -| First CalVer release (`v2026.03`) | Reject loading state saved before `v2026.03` into LocalStack `v2026.03` or later. Persistence was rewritten for several services in the first calendar-versioned release. | - -Loading a state saved with `v2026.03` or later into a newer LocalStack version of the same series remains supported. -For example, a state saved with `v2026.03` can be loaded into `v2026.03.1` or `v2026.04`. - -### Disable compatibility checks - -If you understand the risks and want LocalStack to load state regardless of these rules, start the container with `DISABLE_COMPATIBILITY_RULES=1`. -This bypasses every compatibility rule and lets LocalStack attempt to load the state as-is. - - - -```bash -DISABLE_COMPATIBILITY_RULES=1 PERSISTENCE=1 localstack start -``` - - -```yaml showLineNumbers -image: localstack/localstack-pro -environment: - - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} - - PERSISTENCE=1 - - DISABLE_COMPATIBILITY_RULES=1 -volumes: - - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack" -``` - - -```bash -docker run \ - -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \ - -e PERSISTENCE=1 \ - -e DISABLE_COMPATIBILITY_RULES=1 \ - -v ./volume:/var/lib/localstack \ - -p 4566:4566 \ - localstack/localstack-pro -``` - - - -:::caution -Disabling compatibility rules can leave LocalStack in an inconsistent state. -Use this option only for debugging or when migrating data with a tested workaround in place. -::: - -## Service coverage - -Although we are working to support both snapshot-based persistence and Cloud pods for all AWS services, -there are some common issues, known limitations, and also services that are not well tested for persistence support. -An overview is available [here](#persistence-coverage-overview). - -:::note -When using LocalStack's persistence feature, ports assigned to services (like RDS or Elasticache) when the snapshot was created may not be preserved when loading a saved state. -If you start new services *before* restoring the previous state, these new instances may use ports originally used by the saved services. - -As a result, restored resources may point to invalid or unintended ports. -It is suggested to estore services in the same order as initially deployed, though this is not always reliable. -::: - -Please help us improve persistence support by reporting bugs on our [GitHub Discussion](https://github.com/orgs/localstack/discussions/new/choose). - -## Technical Details - -State persistence in LocalStack works on a per-service basis and uses a custom state serialization protocol based on [Python's pickle mechanism](https://docs.python.org/3/library/pickle.html). -Some services also store application-specific data, which we call _assets_. -For example, when you start an RDS PostgreSQL database, LocalStack not only stores the RDS resource information, but also the PostgreSQL data. -Another example is Kinesis, which persists some data in form of JSON objects per account, or DynamoDB that serializes its stat into an SQLite database per account and region. - -The current LocalStack snapshot is stored into `/var/lib/localstack/state`, and separated into `api_states` (LocalStack internal state), and assets (one directory per service). -Here is what this looks like: - - -- /var/lib/localstack/state # state directory - - api_states # serialized LocalStack stores - - dynamodb - - store.state - - ec2 - - backend.state - - iot - - store.state - - lambda - - store.state - - dynamodb # dynamodb assets - - 000000000000_eu-central-1.db - - 886002141588_us-east-1.db - - kinesis # kinesis assets - - 000000000000.json - - 886002141588.json - - -To load a snapshot, LocalStack traverses the state directory and deserializes state files to loads them into the memory. -When we restore server backends (like an RDS server or DynamoDB server), we make sure that they are configured to use the state stored in the respective asset directory. - -When LocalStack saves snapshots, it has to lock the particular service to avoid state pollution. -That means that, while a snapshot for a particular service is created, all requests to the service are blocked. -Depending on what you are building, you may find this behavior is slowing down your application. -In most cases, the `ON_SHUTDOWN` save strategy should solve this problem. - -import PersistenceCoverage from '../../../../../components/persistence-coverage/PersistenceCoverage.tsx'; - -## Persistence Coverage Overview - - - -### Terminology - -- **Persistence Test Suite**: tested by LocalStack's internal persistence test suite. To test persistence, we use an approach similar to snapshot parity testing. First, we record API responses from LocalStack, then we reset and restore the snapshotted state, and finally, we verify that the same API responses matches with the initial ones. diff --git a/src/content/docs/aws/developer-tools/snapshots/saving-snapshots-locally.md b/src/content/docs/aws/developer-tools/snapshots/saving-snapshots-locally.md new file mode 100644 index 000000000..5d8a749dd --- /dev/null +++ b/src/content/docs/aws/developer-tools/snapshots/saving-snapshots-locally.md @@ -0,0 +1,159 @@ +--- +title: Saving snapshots locally +description: Saving and loading snapshots from local files. +template: doc +tags: ["Base"] +sidebar: + order: 2 +--- + +With Snapshots, you can save the state of your LocalStack instance to a file on disk, then load it back at a later time. This concept is similar to that of desktop-based word processors, spreadsheets, or practically any software that allows saving and loading the program state. + +Loading a snapshot is significantly faster, and far more convenient, than re-creating the same state with infrastructure-as-code tools such as Terraform or CDK, or re-running deployment scripts by hand. Additionally, the dynamic state of those resources (such as database content) is automatically captured, avoiding the need for data-seeding scripts to populate them. + +## Using the `lstk` CLI + +The [`lstk` CLI](/aws/developer-tools/running-localstack/lstk/#snapshot) lets you save your instance's state to a local file and load it back into another instance at a later time. + +For example, starting from an empty emulator instance, create an S3 bucket, an SNS topic, and an SQS queue: + +```bash +lstk start +lstk aws s3 mb s3://bucket1 +lstk aws sns create-topic --name topic1 +lstk aws sqs create-queue --queue-name queue-1 +``` + +The `lstk status` command confirms that the three resources are deployed: + +```bash +lstk status +``` + +```bash title="Output" +✔︎ LocalStack AWS Emulator is running +• Endpoint: localhost.localstack.cloud:4566 +• Container: localstack-aws-dev +• Version: 2026.8.0 +• Uptime: 17s +~ 3 resources · 3 services + SERVICE RESOURCE REGION ACCOUNT + S3 bucket1 global 000000000000 + SNS topic1 us-east-1 000000000000 + SQS http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/queue-1 us-east-1 000000000000 +``` + +To save the state to a local file, run: + +```bash +lstk snapshot save my-snapshot +``` + +```bash title="Output" +✔︎ Snapshot saved to ./my-snapshot.snapshot +• Services: sns, sqs, s3 +• Size: 85.4 KB +``` + +The destination argument is optional. +If you omit it, `lstk` auto-generates a timestamped snapshot file in the current directory: + +```bash +lstk snapshot save +``` + +```bash title="Output" +✔︎ Snapshot saved to ./snapshot-2026-08-04T20-16-49-5e3.snapshot +• Services: sns, sqs, s3 +• Size: 85.4 KB +``` + +Since saving is a common operation, the `lstk save` abbreviation is also available: + +```bash +lstk save +``` + +```bash title="Output" +✔︎ Snapshot saved to ./snapshot-2026-08-04T20-16-49-db4.snapshot +• Services: sns, sqs, s3 +• Size: 85.4 KB +``` + +Restarting the emulator discards all of its state, so `lstk status` now reports that no resources are deployed: + +```bash +lstk restart +lstk status +``` + +```bash title="Output" +✔︎ LocalStack AWS Emulator is running +• Endpoint: localhost.localstack.cloud:4566 +• Container: localstack-aws-dev +• Version: 2026.8.0 +• Uptime: 5s +> Note: No resources deployed +``` + +To load a previously saved snapshot, run: + +```bash +lstk snapshot load my-snapshot +``` + +```bash title="Output" +✔︎ Snapshot loaded from ./my-snapshot.snapshot +``` + +Alternatively, the `lstk load` command is also available: + +```bash +lstk load my-snapshot +``` + +```bash title="Output" +✔︎ Snapshot loaded from ./my-snapshot.snapshot +``` + +Running `lstk status` once more confirms that the bucket, topic, and queue have returned: + +```bash +lstk status +``` + +```bash title="Output" +✔︎ LocalStack AWS Emulator is running +• Endpoint: localhost.localstack.cloud:4566 +• Container: localstack-aws-dev +• Version: 2026.8.0 +• Uptime: 6s +~ 3 resources · 3 services + SERVICE RESOURCE REGION ACCOUNT + S3 bucket1 global 000000000000 + SNS topic1 us-east-1 000000000000 + SQS http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/queue-1 us-east-1 000000000000 +``` + +## Using the LocalStack Console + +The LocalStack Console allows saving a snapshot to a file, then loading it into another LocalStack instance. + +![LocalStack Export/Import State Local Mode](/images/aws/export-import-state-local.png) + +To save the snapshot, follow these steps: + +1. Create AWS resources locally as needed. +2. Navigate to the **Local** tab within the [Export/Import State](https://app.localstack.cloud/inst/default/state) page. +3. Click on the **Export State** button. + This action will initiate the download of a ZIP file. + +The downloaded ZIP file contains your container state, which can be injected into another LocalStack instance for further use. + +To load an existing snapshot, follow these steps: + +1. Navigate to the **Local** tab within the [Export/Import State](https://app.localstack.cloud/inst/default/state) page. +2. Upload the ZIP file that contains your container state. + This action will restore your previously saved AWS resources. + +To confirm the successful injection of the container state, visit the respective [Resource Browser](https://app.localstack.cloud/inst/default/resources) for the services and verify the resources. diff --git a/src/content/docs/aws/developer-tools/snapshots/saving-snapshots-to-s3.md b/src/content/docs/aws/developer-tools/snapshots/saving-snapshots-to-s3.md new file mode 100644 index 000000000..874adc8b8 --- /dev/null +++ b/src/content/docs/aws/developer-tools/snapshots/saving-snapshots-to-s3.md @@ -0,0 +1,88 @@ +--- +title: Saving snapshots to S3 +description: Save snapshots directly to an Amazon S3 bucket, as an alternative to Cloud Pods or local storage. +template: doc +tags: ["Base"] +sidebar: + order: 4 +--- + +By default, Cloud Pod artifacts are stored on the LocalStack platform. +However, if your organization's data regulations or sovereignty requirements prohibit storing snapshots in LocalStack's managed storage, saving directly to your own Amazon S3 bucket is the recommended solution for keeping full control over where that data lives. + +When saving, loading, or listing snapshots in your own S3 bucket, `lstk` uses pre-signed S3 URLs to transfer the data directly between the emulator and your bucket, without proxying it through LocalStack's platform. + +## Using the `lstk` CLI + +The [`lstk snapshot`](/aws/developer-tools/running-localstack/lstk/#snapshot) command lets you save, load, and list snapshots stored in your own S3 bucket by passing an `s3://bucket/prefix` location alongside a snapshot name. + +The initial step is to export the necessary AWS credentials in your terminal session. + +```bash +export AWS_ACCESS_KEY_ID=... +export AWS_SECRET_ACCESS_KEY=... +``` + +To obtain credentials automatically, use [AWS SSO CLI](https://github.com/synfinatic/aws-sso-cli). Alternatively, set `AWS_PROFILE` or pass `--profile ` to have `lstk` read credentials from a named AWS profile instead of the environment. + +To save a snapshot to your S3 bucket, provide a snapshot name followed by the `s3://` location: + +```bash +lstk snapshot save my-snapshot s3://ls-s3-bucket-example +``` + +```bash title="Output" +✔︎ Snapshot saved to s3://ls-s3-bucket-example as "my-snapshot" +• Version: 1 +• Size: 74.6 KB +``` + +:::note +On LocalStack `v2026.08` or later, snapshots transfer to a real Amazon S3 bucket with [transparent endpoint injection](/aws/customization/networking/transparent-endpoint-injection) left enabled, as it is by default. No extra configuration is needed. + +On versions before `v2026.08`, transparent endpoint injection must be disabled. +Otherwise LocalStack's [DNS server](/aws/customization/networking/dns-server) resolves the AWS domains back to the emulator, and the transfer never reaches your bucket — typically surfacing as a TLS certificate validation error. + +Disable this feature by setting [`DNS_ADDRESS=0`](/aws/customization/configuration-options/) when starting the emulator, which turns off transparent endpoint injection application-wide. +On the command line, use `LOCALSTACK_DNS_ADDRESS=0 lstk start` — host variables prefixed with `LOCALSTACK_` are forwarded to the emulator. +In a `config.toml` [environment profile](/aws/developer-tools/running-localstack/lstk/#passing-environment-variables-to-the-container), use the unprefixed form `DNS_ADDRESS = "0"`. +::: + +Once the snapshot has been saved, you can confirm the presence of the snapshot artifacts in the S3 bucket by running: + +```bash +aws s3 ls s3://ls-s3-bucket-example +``` + +```bash title="Output" +2026-08-05 10:08:55 76390 localstack-pod-my-snapshot-state-1.zip +``` + +You can then use `lstk snapshot load` to load the previously saved snapshot: + +```bash +lstk snapshot load my-snapshot s3://ls-s3-bucket-example +``` + +```bash title="Output" +✔︎ Snapshot loaded from s3://ls-s3-bucket-example (my-snapshot) +``` + +Similarly, you can list the snapshots stored in this bucket with `lstk snapshot list`: + +```bash +lstk snapshot list s3://ls-s3-bucket-example +``` + +```bash title="Output" +~ 1 snapshot + + NAME VERSION + my-snapshot 1 +``` + +:::note +Because data transfer is performed by the emulator rather than the CLI, saving, loading, and listing snapshots in your own S3 bucket require a **running emulator**. +::: + +Comprehensive instructions on using the `lstk snapshot` CLI command, including credential resolution order, are found in the [`lstk` CLI Guide](/aws/developer-tools/running-localstack/lstk/#s3-remotes). diff --git a/src/content/docs/aws/developer-tools/snapshots/service-coverage.mdx b/src/content/docs/aws/developer-tools/snapshots/service-coverage.mdx new file mode 100644 index 000000000..1358c64cb --- /dev/null +++ b/src/content/docs/aws/developer-tools/snapshots/service-coverage.mdx @@ -0,0 +1,91 @@ +--- +title: Service coverage +description: Snapshot compatibility rules and service coverage of LocalStack's snapshot mechanism. +template: doc +sidebar: + order: 7 +tags: ["Base"] +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; +import PersistenceCoverage from '../../../../../components/persistence-coverage/PersistenceCoverage.tsx'; + +This page covers two topics: the compatibility rules LocalStack enforces when loading a snapshot, and the current level of snapshot support across AWS services. + +## Snapshot compatibility + +The internal data structures inside a LocalStack emulator change over time as services evolve. +To prevent silently loading state into an incompatible runtime, LocalStack ships a set of compatibility rules that compare the LocalStack version recorded in the snapshot with the version of the running emulator. +These rules apply to all snapshots, whether saved locally to a file, saved to a Cloud Pod, or implicitly saved when persistence is enabled. + +If a rule rejects the snapshot, LocalStack does not load it, and logs the reason. +The rules currently enforced are: + +| Rule | Behavior | +| - | - | +| Forward compatibility | Reject loading a snapshot into a LocalStack emulator older than the one that produced it. | +| First CalVer release (`v2026.03`) | Reject loading a snapshot saved before `v2026.03` into LocalStack `v2026.03` or later. The snapshot mechanism was rewritten for several services in the first calendar-versioned release. | + +Loading a snapshot saved with `v2026.03` or later into a newer LocalStack version of the same series remains supported. +For example, a snapshot saved with `v2026.03` can be loaded into `v2026.03.1` or `v2026.04`. + +### Disable compatibility checks + +If you understand the risks and want LocalStack to load a snapshot regardless of these rules, start the container with `DISABLE_COMPATIBILITY_RULES=1`. +This bypasses every compatibility rule and lets LocalStack attempt to load the state as-is. + + + +```bash +LOCALSTACK_DISABLE_COMPATIBILITY_RULES=1 lstk start --persist +``` + + +```yaml showLineNumbers +image: localstack/localstack-pro +environment: + - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} + - PERSISTENCE=1 + - DISABLE_COMPATIBILITY_RULES=1 +volumes: + - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack" +``` + + +```bash +docker run \ + -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \ + -e PERSISTENCE=1 \ + -e DISABLE_COMPATIBILITY_RULES=1 \ + -v ./volume:/var/lib/localstack \ + -p 4566:4566 \ + localstack/localstack-pro +``` + + + +:::caution +Disabling compatibility rules can leave LocalStack in an inconsistent state. +Use this option only for debugging or when migrating data with a tested workaround in place. +::: + +## Service coverage + +Although we are working to support snapshots for all AWS services, +there are some common issues, known limitations, and services that are not well tested for snapshot support. +See the [snapshot coverage overview](#snapshot-coverage-overview) below for the current state of support. + +For example, when using LocalStack's snapshot feature, ports assigned to certain services (such as RDS or ElastiCache) may not be preserved when reloading that snapshot. +If you start new services *before* restoring the snapshot, these new instances may use ports originally used by the saved services. + +As a result, restored resources may point to invalid or unintended ports. +We suggest restoring services in the same order they were initially deployed, though this is not always reliable. + +If you encounter a limitation or bug with snapshot support, please [contact support](/aws/help-support/get-help/). + +## Snapshot coverage overview + + + +The **Persistence Test Suite** column indicates whether a service is covered by LocalStack's internal persistence test suite. We first record API responses when querying the resources in the LocalStack emulator, then reset the emulator and restore the snapshotted +state. Finally, we verify that the API responses match those recorded earlier. diff --git a/src/content/docs/aws/services/account.mdx b/src/content/docs/aws/services/account.mdx index 26bf9f1be..2a81139d2 100644 --- a/src/content/docs/aws/services/account.mdx +++ b/src/content/docs/aws/services/account.mdx @@ -23,7 +23,7 @@ It's important to note that LocalStack doesn't offer a programmatic interface to ## Getting started -This guide is designed for users who are new to Account and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users who are new to Account and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to put contact information, fetch account details, and attach an alternate contact to your account. @@ -34,7 +34,7 @@ You can use the [`PutContactInformation`](https://docs.aws.amazon.com/accounts/l Run the following command to add contact information to your account: ```bash showshowLineNumbers -awslocal account put-contact-information \ +lstk aws account put-contact-information \ --contact-information '{ "FullName": "Jane Doe", "PhoneNumber": "+XXXXXXXXX", @@ -52,7 +52,7 @@ You can use the [`GetContactInformation`](https://docs.aws.amazon.com/accounts/l Run the following command to fetch the contact information for your account: ```bash -awslocal account get-contact-information +lstk aws account get-contact-information ``` ```bash title="Output" showshowLineNumbers @@ -75,7 +75,7 @@ You can attach an alternate contact using [`PutAlternateContact`](https://docs.a Run the following command to attach an alternate contact to your account: ```bash showshowLineNumbers -awslocal account put-alternate-contact \ +lstk aws account put-alternate-contact \ --alternate-contact-type "BILLING" \ --email-address "bill@ing.com" \ --name "Bill Ing" \ diff --git a/src/content/docs/aws/services/acm-pca.mdx b/src/content/docs/aws/services/acm-pca.mdx index 03b29967f..5c01e07e1 100644 --- a/src/content/docs/aws/services/acm-pca.mdx +++ b/src/content/docs/aws/services/acm-pca.mdx @@ -18,7 +18,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users who are new to ACM PCA and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users who are new to ACM PCA and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. We will follow the procedure to create and install a certificate for a single-level hierarchy CA hosted by ACM PCA. ### Create a CA @@ -27,7 +27,7 @@ Start by creating a new Certificate Authority with ACM PCA using the [`CreateCer This command sets up a new CA with specified configurations for key algorithm, signing algorithm, and subject information. ```bash -awslocal acm-pca create-certificate-authority \ +lstk aws acm-pca create-certificate-authority \ --certificate-authority-configuration '{ "KeyAlgorithm":"RSA_2048", "SigningAlgorithm":"SHA256WITHRSA", @@ -53,7 +53,7 @@ To retrieve the detailed information about the created Certificate Authority, us This command returns the detailed information about the CA, including the CA's ARN, status, and configuration. ```bash -awslocal acm-pca describe-certificate-authority \ +lstk aws acm-pca describe-certificate-authority \ --certificate-authority-arn arn:aws:acm-pca:eu-central-1:000000000000:certificate-authority/0b20353f-ce7a-4de4-9b82-e06903a893ff ``` @@ -94,7 +94,7 @@ In the following steps, we will create and attach a certificate for this CA. Use the [`GetCertificateAuthorityCsr`](https://docs.aws.amazon.com/privateca/latest/APIReference/API_GetCertificateAuthorityCsr.html) operation to obtain the Certificate Signing Request (CSR) for the CA. ```bash -awslocal acm-pca get-certificate-authority-csr \ +lstk aws acm-pca get-certificate-authority-csr \ --certificate-authority-arn arn:aws:acm-pca:eu-central-1:000000000000:certificate-authority/0b20353f-ce7a-4de4-9b82-e06903a893ff \ --output text | tee ca.csr ``` @@ -102,7 +102,7 @@ awslocal acm-pca get-certificate-authority-csr \ Next, issue the certificate for the CA using this CSR. ```bash -awslocal acm-pca issue-certificate \ +lstk aws acm-pca issue-certificate \ --csr fileb://ca.csr \ --signing-algorithm SHA256WITHRSA \ --template-arn arn:aws:acm-pca:::template/RootCACertificate/V1 \ @@ -123,14 +123,14 @@ The CA certificate is now created and its ARN is indicated by the `CertificateAr Finally, we retrieve the signed certificate with [`GetCertificate`](https://docs.aws.amazon.com/privateca/latest/APIReference/API_GetCertificate.html) and import it using [`ImportCertificateAuthorityCertificate`](https://docs.aws.amazon.com/privateca/latest/APIReference/API_ImportCertificateAuthorityCertificate.html). ```bash -awslocal acm-pca get-certificate \ +lstk aws acm-pca get-certificate \ --certificate-authority-arn arn:aws:acm-pca:eu-central-1:000000000000:certificate-authority/0b20353f-ce7a-4de4-9b82-e06903a893ff \ --certificate-arn arn:aws:acm-pca:eu-central-1:000000000000:certificate-authority/0b20353f-ce7a-4de4-9b82-e06903a893ff/certificate/17ef7bbf3cc6471ba3ef0707119b8392 \ --output text | tee cert.pem ``` ```bash -awslocal acm-pca import-certificate-authority-certificate \ +lstk aws acm-pca import-certificate-authority-certificate \ --certificate-authority-arn arn:aws:acm-pca:eu-central-1:000000000000:certificate-authority/0b20353f-ce7a-4de4-9b82-e06903a893ff \ --certificate fileb://cert.pem ``` @@ -139,7 +139,7 @@ The CA is now ready for use. You can verify this by checking its status: ```bash -awslocal acm-pca describe-certificate-authority \ +lstk aws acm-pca describe-certificate-authority \ --certificate-authority-arn arn:aws:acm-pca:eu-central-1:000000000000:certificate-authority/0b20353f-ce7a-4de4-9b82-e06903a893ff \ --query CertificateAuthority.Status \ --output text @@ -196,7 +196,7 @@ Next, using [`IssueCertificate`](https://docs.aws.amazon.com/privateca/latest/AP Note that there is no [certificate template](https://docs.aws.amazon.com/privateca/latest/userguide/UsingTemplates.html) specified which causes the end-entity certificate to be issued by default. ```bash -awslocal acm-pca issue-certificate \ +lstk aws acm-pca issue-certificate \ --certificate-authority-arn arn:aws:acm-pca:eu-central-1:000000000000:certificate-authority/0b20353f-ce7a-4de4-9b82-e06903a893ff \ --csr fileb://local-csr.pem \ --signing-algorithm "SHA256WITHRSA" \ @@ -231,7 +231,7 @@ Use the [`TagCertificateAuthority`](https://docs.aws.amazon.com/privateca/latest This command adds the specified tags to the specified CA. ```bash -awslocal acm-pca tag-certificate-authority \ +lstk aws acm-pca tag-certificate-authority \ --certificate-authority-arn arn:aws:acm-pca:us-east-1:000000000000:certificate-authority/f38ee966-bc23-40f8-8143-e981aee73600 \ --tags Key=Admin,Value=Alice ``` @@ -240,7 +240,7 @@ After tagging your Certificate Authority, you may want to view these tags. You can use the [`ListTags`](https://docs.aws.amazon.com/privateca/latest/APIReference/API_ListTags.html) API to list all the tags associated with the specified CA. ```bash -awslocal acm-pca list-tags \ +lstk aws acm-pca list-tags \ --certificate-authority-arn arn:aws:acm-pca:us-east-1:000000000000:certificate-authority/f38ee966-bc23-40f8-8143-e981aee73600 \ --max-results 10 ``` diff --git a/src/content/docs/aws/services/acm.mdx b/src/content/docs/aws/services/acm.mdx index 1f011be58..d923b0232 100644 --- a/src/content/docs/aws/services/acm.mdx +++ b/src/content/docs/aws/services/acm.mdx @@ -20,7 +20,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users who are new to ACM and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users who are new to ACM and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. ### Request a public certificate @@ -29,7 +29,7 @@ Specify the domain name you want to request the certificate for, and any additio Here's an example command: ```bash showshowLineNumbers -awslocal acm request-certificate \ +lstk aws acm request-certificate \ --domain-name www.example.com \ --validation-method DNS \ --idempotency-token 1234 \ @@ -51,7 +51,7 @@ This command returns a list of the ARNs of all the certificates that have been r Here's an example command: ```bash -awslocal acm list-certificates --max-items 10 +lstk aws acm list-certificates --max-items 10 ``` ### Describe the certificate @@ -61,7 +61,7 @@ Provide the ARN of the certificate you want to view, and this command will retur Here's an example command: ```bash -awslocal acm describe-certificate --certificate-arn arn:aws:acm::account:certificate/ +lstk aws acm describe-certificate --certificate-arn arn:aws:acm::account:certificate/ ``` ### Delete the certificate @@ -70,7 +70,7 @@ Finally you can use the [`DeleteCertificate` API](https://docs.aws.amazon.com/ac Here's an example command: ```bash -awslocal acm delete-certificate --certificate-arn arn:aws:acm::account:certificate/ +lstk aws acm delete-certificate --certificate-arn arn:aws:acm::account:certificate/ ``` ## Resource Browser diff --git a/src/content/docs/aws/services/apigateway.mdx b/src/content/docs/aws/services/apigateway.mdx index 2fc0cbd14..4118802ff 100644 --- a/src/content/docs/aws/services/apigateway.mdx +++ b/src/content/docs/aws/services/apigateway.mdx @@ -21,7 +21,7 @@ The supported APIs are available on the API coverage section for [API Gateway V1 ## Getting started -This guide is designed for users new to API Gateway and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to API Gateway and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will use the Lambda proxy integration to integrate an API method with a Lambda function. @@ -49,12 +49,12 @@ module.exports = { ``` The above code defines a function named `apiHandler` that returns a response with a status code of `200` and a body containing the string `Hello from Lambda`. -Zip the file and upload it to LocalStack using the `awslocal` CLI. +Zip the file and upload it to LocalStack using the `lstk aws` command. Run the following command: ```bash showshowLineNumbers zip function.zip lambda.js -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name apigw-lambda \ --runtime nodejs16.x \ --handler lambda.apiHandler \ @@ -71,7 +71,7 @@ We will use the API Gateway's [`CreateRestApi`](https://docs.aws.amazon.com/apig Here's an example command: ```bash -awslocal apigateway create-rest-api --name 'API Gateway Lambda integration' +lstk aws apigateway create-rest-api --name 'API Gateway Lambda integration' ``` This creates a new REST API named `API Gateway Lambda integration`. @@ -99,7 +99,7 @@ You'll need this ID for the next step. Use the REST API ID generated in the previous step to fetch the resources for the API, using the [`GetResources`](https://docs.aws.amazon.com/apigateway/latest/api/API_GetResources.html) API: ```bash -awslocal apigateway get-resources --rest-api-id +lstk aws apigateway get-resources --rest-api-id ``` ```bash title="Output" @@ -122,7 +122,7 @@ Create a new resource for the API using the [`CreateResource`](https://docs.aws. Use the ID of the resource returned in the previous step as the parent ID: ```bash showshowLineNumbers -awslocal apigateway create-resource \ +lstk aws apigateway create-resource \ --rest-api-id \ --parent-id \ --path-part "{somethingId}" @@ -146,7 +146,7 @@ Add a `GET` method to the resource using the [`PutMethod`](https://docs.aws.amaz Use the ID of the resource returned in the previous step as the Resource ID: ```bash showshowLineNumbers -awslocal apigateway put-method \ +lstk aws apigateway put-method \ --rest-api-id \ --resource-id \ --http-method GET \ @@ -168,7 +168,7 @@ awslocal apigateway put-method \ Now, create a new integration for the method using the [`PutIntegration`](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html) API. ```bash showshowLineNumbers -awslocal apigateway put-integration \ +lstk aws apigateway put-integration \ --rest-api-id \ --resource-id \ --http-method GET \ @@ -186,7 +186,7 @@ We can now proceed with the deployment before invoking the API. Create a new deployment for the API using the [`CreateDeployment`](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html) API: ```bash -awslocal apigateway create-deployment \ +lstk aws apigateway create-deployment \ --rest-api-id \ --stage-name dev ``` @@ -346,10 +346,10 @@ functions: ``` Upon deployment of the Serverless project, LocalStack creates a new API Gateway V2 endpoint. -To retrieve the list of APIs and verify the WebSocket endpoint, you can use the `awslocal` CLI: +To retrieve the list of APIs and verify the WebSocket endpoint, you can use the `lstk aws` CLI: ```bash -awslocal apigatewayv2 get-apis +lstk aws apigatewayv2 get-apis ``` ```bash title="Output" @@ -377,7 +377,7 @@ To push data from a backend service to the WebSocket connection, you can use the In LocalStack, use the following CLI command (replace `` with your WebSocket connection ID): ```bash -awslocal apigatewaymanagementapi \ +lstk aws apigatewaymanagementapi \ post-to-connection \ --connection-id '' \ --data '{"msg": "Hi"}' @@ -392,7 +392,7 @@ To assign a custom ID to an API Gateway REST API, use the `create-rest-api` comm The following example assigns the custom ID `"myid123"` to the API: ```bash -awslocal apigateway create-rest-api --name my-api --tags '{"_custom_id_":"myid123"}' +lstk aws apigateway create-rest-api --name my-api --tags '{"_custom_id_":"myid123"}' ``` ```bash title="Output" @@ -405,7 +405,7 @@ awslocal apigateway create-rest-api --name my-api --tags '{"_custom_id_":"myid12 You can also configure the protocol type, the possible values being `HTTP` and `WEBSOCKET`: ```bash showshowLineNumbers -awslocal apigatewayv2 create-api \ +lstk aws apigatewayv2 create-api \ --name=my-api \ --protocol-type=HTTP --tags="_custom_id_=my-api" { diff --git a/src/content/docs/aws/services/appconfig.mdx b/src/content/docs/aws/services/appconfig.mdx index 53f867f29..61853e687 100644 --- a/src/content/docs/aws/services/appconfig.mdx +++ b/src/content/docs/aws/services/appconfig.mdx @@ -15,7 +15,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to AppConfig and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to AppConfig and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create an AppConfig application, environment, configuration profiles & feature flags, and deploy the configuration with the AWS CLI. @@ -27,7 +27,7 @@ The application is a folder/directory that contains the configuration data for y The following command creates an application named `my-app`: ```bash -awslocal appconfig create-application \ +lstk aws appconfig create-application \ --name my-app \ --description "My application" ``` @@ -47,7 +47,7 @@ An environment consists of the deployment group of your AppConfig applications. The following command creates an environment named `my-app-env`: ```bash -awslocal appconfig create-environment \ +lstk aws appconfig create-environment \ --application-id 400c285 \ --name my-app-env \ --description "My application environment" @@ -73,7 +73,7 @@ A configuration profile contains for the configurations of your AppConfig applic The following command creates a configuration profile named `my-app-config`: ```bash -awslocal appconfig create-configuration-profile \ +lstk aws appconfig create-configuration-profile \ --application-id 400c285 \ --name my-app-config \ --location-uri hosted \ @@ -110,7 +110,7 @@ You can now use the [`CreateHostedConfigurationVersion`](https://docs.aws.amazon The following command creates a hosted configuration version for the configuration profile you created in the previous step: ```bash -awslocal appconfig create-hosted-configuration-version \ +lstk aws appconfig create-hosted-configuration-version \ --application-id 400c285 \ --configuration-profile-id 7d748f9 \ --content-type "application/json" \ @@ -134,7 +134,7 @@ A deployment strategy defines important criteria for rolling out your configurat The following command creates a deployment strategy named `my-app-deployment-strategy`: ```bash -awslocal appconfig create-deployment-strategy \ +lstk aws appconfig create-deployment-strategy \ --name my-app-deployment-strategy \ --description "My application deployment strategy" \ --deployment-duration-in-minutes 10 \ @@ -155,7 +155,7 @@ You can now use the [`StartDeployment`](https://docs.aws.amazon.com/appconfig/la The following command deploys the configuration to the environment you created in the previous step: ```bash -awslocal appconfig start-deployment \ +lstk aws appconfig start-deployment \ --application-id 400c285 \ --environment-id 3695ea3 \ --deployment-strategy-id f2f2225 \ diff --git a/src/content/docs/aws/services/application-autoscaling.mdx b/src/content/docs/aws/services/application-autoscaling.mdx index a035f1fa7..0658f3116 100644 --- a/src/content/docs/aws/services/application-autoscaling.mdx +++ b/src/content/docs/aws/services/application-autoscaling.mdx @@ -19,7 +19,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting Started -This guide is designed for users new to Application Auto Scaling and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Application Auto Scaling and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how you can configure auto scaling to handle a heavy workload for your Lambda function. @@ -42,7 +42,7 @@ Run the following command to create a new Lambda function using the [`CreateFunc ```bash zip function.zip index.js -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name autoscaling-example \ --runtime nodejs18.x \ --zip-file fileb://function.zip \ @@ -57,8 +57,8 @@ We will use the [`PublishVersion`](https://docs.aws.amazon.com/cli/latest/refere Run the following commands: ```bash -awslocal lambda publish-version --function-name autoscaling-example -awslocal lambda create-alias \ +lstk aws lambda publish-version --function-name autoscaling-example +lstk aws lambda create-alias \ --function-name autoscaling-example \ --description "alias for blue version of function" \ --function-version 1 \ @@ -73,7 +73,7 @@ We will specify the `--service-namespace` as `lambda`, `--scalable-dimension` as Run the following command to register the scalable target: ```bash -awslocal application-autoscaling register-scalable-target \ +lstk aws application-autoscaling register-scalable-target \ --service-namespace lambda \ --scalable-dimension lambda:function:ProvisionedConcurrency \ --resource-id function:autoscaling-example:BLUE \ @@ -86,7 +86,7 @@ You can create a scheduled action that scales out by specifying the `--schedule` Run the following command to create a scheduled action using the [`PutScheduledAction`](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/put-scheduled-action.html) API: ```bash -awslocal application-autoscaling put-scheduled-action \ +lstk aws application-autoscaling put-scheduled-action \ --service-namespace lambda \ --scalable-dimension lambda:function:ProvisionedConcurrency \ --resource-id function:autoscaling-example:BLUE \ @@ -98,7 +98,7 @@ awslocal application-autoscaling put-scheduled-action \ You can confirm if the scheduled action exists using [`DescribeScheduledActions`](https://docs.aws.amazon.com/cli/latest/reference/application-autoscaling/describe-scheduled-actions.html) API: ```bash -awslocal application-autoscaling describe-scheduled-actions \ +lstk aws application-autoscaling describe-scheduled-actions \ --service-namespace lambda ``` @@ -111,7 +111,7 @@ When metrics lack data due to minimal application load, Application Auto Scaling Run the following command to create a target-tracking scaling policy: ```bash -awslocal application-autoscaling put-scaling-policy \ +lstk aws application-autoscaling put-scaling-policy \ --service-namespace lambda \ --scalable-dimension lambda:function:ProvisionedConcurrency \ --resource-id function:events-example:BLUE \ diff --git a/src/content/docs/aws/services/appsync.mdx b/src/content/docs/aws/services/appsync.mdx index 3d464408c..0bc0cb7ec 100644 --- a/src/content/docs/aws/services/appsync.mdx +++ b/src/content/docs/aws/services/appsync.mdx @@ -14,7 +14,7 @@ AWS AppSync is a fully managed API management service that connects applications LocalStack allows you to use the AppSync APIs in your local environment to connect your applications and services to data and events. The supported APIs are available on our [API Coverage section](#api-coverage), which provides information on the extent of AppSync's integration with LocalStack. -This guide is designed for users new to **AppSync** in LocalStack, and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to **AppSync** in LocalStack, and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. LocalStack supports two primary ways to work with AppSync, GraphQL and Events API. @@ -32,7 +32,7 @@ Use schemas and resolvers to interact with data sources like DynamoDB. Create serverless GraphQL APIs to query databases, microservices, and other APIs. AppSync allows you to define your data models and business logic using a declarative approach, and connect to various data sources, including other AWS services, relational databases, and custom data sources. -This guide is designed for users new to AppSync and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to AppSync and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create an AppSync API with a DynamoDB data source using the AWS CLI. @@ -43,7 +43,7 @@ You can create a DynamoDB table using the [`CreateTable`](https://docs.aws.amazo Execute the following command to create a table named `DynamoDBNotesTable` with a primary key named `NoteId`: ```bash -awslocal dynamodb create-table \ +lstk aws dynamodb create-table \ --table-name DynamoDBNotesTable \ --attribute-definitions AttributeName=NoteId,AttributeType=S \ --key-schema AttributeName=NoteId,KeyType=HASH \ @@ -54,7 +54,7 @@ After the table is created, you can use the [`ListTables`](https://docs.aws.amaz Run the following command to list all tables in your running LocalStack container: ```bash -awslocal dynamodb list-tables +lstk aws dynamodb list-tables ``` ```bash title="Output" @@ -71,7 +71,7 @@ You can create a GraphQL API using the [`CreateGraphqlApi`](https://docs.aws.ama Execute the following command to create a GraphQL API named `NotesApi`: ```bash -awslocal appsync create-graphql-api \ +lstk aws appsync create-graphql-api \ --name NotesApi \ --authentication-type API_KEY ``` @@ -97,7 +97,7 @@ You can now create an API key for your GraphQL API using the [`CreateApiKey`](ht Execute the following command to create an API key for your GraphQL API: ```bash -awslocal appsync create-api-key \ +lstk aws appsync create-api-key \ --api-id 014d18d0c2b149ee8b66f39173 ``` @@ -142,7 +142,7 @@ You can start the schema creation process using the [`StartSchemaCreation`](http Execute the following command to start the schema creation process: ```bash -awslocal appsync start-schema-creation \ +lstk aws appsync start-schema-creation \ --api-id 014d18d0c2b149ee8b66f39173 \ --definition file://schema.graphql ``` @@ -159,7 +159,7 @@ You can create a data source using the [`CreateDataSource`](https://docs.aws.ama Execute the following command to create a data source named `DynamoDBNotesTable`: ```bash -awslocal appsync create-data-source \ +lstk aws appsync create-data-source \ --name AppSyncDB \ --api-id 014d18d0c2b149ee8b66f39173 \ --type AMAZON_DYNAMODB \ @@ -187,7 +187,7 @@ You can create a custom `request-mapping-template.vtl` and `response-mapping-tem Execute the following command to create a VTL resolver attached to the `PaginatedNotes.notes` field: ```bash -awslocal appsync create-resolver \ +lstk aws appsync create-resolver \ --api-id 014d18d0c2b149ee8b66f39173 \ --type Query \ --field PaginatedNotes.notes \ @@ -410,7 +410,7 @@ You can create an Events API using the [CreateApi](https://docs.aws.amazon.com/a Note the `apiId`, `dns.REALTIME` and `dns.HTTP` in the outputs as it will be reused as ``, `` and `` for the remainder of this example. ```bash -awslocal appsync create-api \ +lstk aws appsync create-api \ --name my-api \ --event-config '{ "authProviders":[{"authType": "API_KEY"}], @@ -442,7 +442,7 @@ awslocal appsync create-api \ You can create an `channelNamespace` using the [CreateChannelNamespace](https://docs.aws.amazon.com/appsync/latest/APIReference/API_CreateChannelNamespace.html) API. At least one `channelNamespace` is required in order to subscribe and publish to it. ```bash -awslocal appsync create-channel-namespace \ +lstk aws appsync create-channel-namespace \ --api-id \ --name "default" ``` @@ -468,7 +468,7 @@ You can create an Api Key using the [CreateApiKey](https://docs.aws.amazon.com/a ```bash -awslocal appsync create-api-key --api-id +lstk aws appsync create-api-key --api-id ``` ```bash title="Output" @@ -619,7 +619,7 @@ You can employ a pre-defined ID during the creation of AppSync APIs by utilizing For example, the following command will create a GraphQL API with the ID `faceb00c`. `--tags` can also be passed when creating an Events API, and both the API id and the endpoint id will use the provided id. ```bash -awslocal appsync create-graphql-api \ +lstk aws appsync create-graphql-api \ --name my-api \ --authentication-type API_KEY \ --tags _custom_id_=faceb00c @@ -666,7 +666,7 @@ See the AWS documentation for [`evaluate-mapping-template`](https://awscli.amazo ### VTL template evaluation ```bash -awslocal appsync evaluate-mapping-template \ +lstk aws appsync evaluate-mapping-template \ --template '$ctx.result' \ --context '{"result":"ok"}' ``` @@ -681,7 +681,7 @@ awslocal appsync evaluate-mapping-template \ ### JavaScript code evaluation ```bash -awslocal appsync evaluate-code \ +lstk aws appsync evaluate-code \ --runtime name=APPSYNC_JS,runtimeVersion=1.0.0 \ --function request \ --code 'export function request(ctx) { return ctx.result; } export function response(ctx) {}' \ diff --git a/src/content/docs/aws/services/athena.mdx b/src/content/docs/aws/services/athena.mdx index 066ab1de7..944765b71 100644 --- a/src/content/docs/aws/services/athena.mdx +++ b/src/content/docs/aws/services/athena.mdx @@ -19,7 +19,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Athena and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Athena and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create an Athena table and run a query against it in addition to reading the results with the AWS CLI. @@ -37,7 +37,7 @@ You can create an S3 bucket using the [`mb`](https://docs.aws.amazon.com/cli/lat Run the following command to create a bucket named `athena-bucket`: ```bash -awslocal s3 mb s3://athena-bucket +lstk aws s3 mb s3://athena-bucket ``` You can create some sample data using the following commands: @@ -50,7 +50,7 @@ echo "LocalStack,Athena" >> data.csv You can upload the data to your bucket using the [`cp`](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html) command: ```bash -awslocal s3 cp data.csv s3://athena-bucket/data/ +lstk aws s3 cp data.csv s3://athena-bucket/data/ ``` ### Create an Athena table @@ -59,7 +59,7 @@ You can create an Athena table using the [`CreateTable`](https://docs.aws.amazon Run the following command to create a table named `athena_table`: ```bash -awslocal athena start-query-execution \ +lstk aws athena start-query-execution \ --query-string "create external table tbl01 (name STRING, surname STRING) ROW FORMAT DELIMITED FIELDS TERMINATED BY ',' LOCATION 's3://athena-bucket/data/';" --result-configuration "OutputLocation=s3://athena-bucket/output/" ``` @@ -73,7 +73,7 @@ You can retrieve information about the query execution using the [`GetQueryExecu Run the following command: ```bash -awslocal athena get-query-execution --query-execution-id 593acab7 +lstk aws athena get-query-execution --query-execution-id 593acab7 ``` Replace `593acab7` with the `QueryExecutionId` returned by the [`StartQueryExecution`](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartQueryExecution.html) API. @@ -84,14 +84,14 @@ You can get the output of the query using the [`GetQueryResults`](https://docs.a Run the following command: ```bash -awslocal athena get-query-results --query-execution-id 593acab7 +lstk aws athena get-query-results --query-execution-id 593acab7 ``` You can now read the data from the `tbl01` table and retrieve the data from S3 that was mentioned in your table creation statement. Run the following command: ```bash -awslocal athena start-query-execution \ +lstk aws athena start-query-execution \ --query-string "select * from tbl01;" --result-configuration "OutputLocation=s3://athena-bucket/output/" ``` @@ -101,7 +101,7 @@ You can copy the `ResultConfiguration` from the output and use it to retrieve th Run the following command: ```bash -awslocal s3 cp s3://athena-bucket/output/593acab7.csv . +lstk aws s3 cp s3://athena-bucket/output/593acab7.csv . cat 593acab7.csv ``` @@ -124,17 +124,17 @@ wget https://localstack-assets.s3.amazonaws.com/aws-sample-athena-delta-lake.zip unzip aws-sample-athena-delta-lake.zip; rm aws-sample-athena-delta-lake.zip ``` -We can then create an S3 bucket in LocalStack using the [`awslocal`](https://github.com/localstack/awscli-local) command line, and upload the files to the bucket: +We can then create an S3 bucket in LocalStack using the [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command line, and upload the files to the bucket: ```bash -awslocal s3 mb s3://test -awslocal s3 sync /tmp/delta-lake-sample s3://test +lstk aws s3 mb s3://test +lstk aws s3 sync /tmp/delta-lake-sample s3://test ``` Next, we create the table definitions in Athena: ```bash -awslocal athena start-query-execution \ +lstk aws athena start-query-execution \ --query-string "CREATE EXTERNAL TABLE test (product_id string, product_name string, \ price bigint, currency string, category string, updated_at double) \ LOCATION 's3://test/' TBLPROPERTIES ('table_type'='DELTA')" @@ -147,11 +147,11 @@ Finally, we can now run a `SELECT` query to extract data from the Delta Lake tab To query Delta Lake tables, specify `Catalog=deltalake` in the `QueryExecutionContext`: ```bash -queryId=$(awslocal athena start-query-execution \ +queryId=$(lstk aws athena start-query-execution \ --query-string "SELECT * FROM test" \ --query-execution-context "Database=default,Catalog=deltalake" \ --result-configuration "OutputLocation=s3://test/output/" | jq -r .QueryExecutionId) -awslocal athena get-query-results --query-execution-id $queryId +lstk aws athena get-query-results --query-execution-id $queryId ``` The query should yield a result similar to the output below: @@ -196,7 +196,7 @@ LOCATION 's3://mybucket/prefix/' TBLPROPERTIES ( 'table_type' = 'ICEBERG' ) To query Iceberg tables, specify `Catalog=iceberg` in the `QueryExecutionContext`: ```bash -awslocal athena start-query-execution \ +lstk aws athena start-query-execution \ --query-string "SELECT * FROM mytable" \ --query-execution-context "Database=default,Catalog=iceberg" \ --result-configuration "OutputLocation=s3://mybucket/output/" @@ -236,7 +236,7 @@ Create a table bucket and a namespace in S3 Tables. The bucket holds your Iceberg tables and the namespace organizes them. ```bash -awslocal s3tables create-table-bucket --name athena-doc-bucket +lstk aws s3tables create-table-bucket --name athena-doc-bucket ``` ```bash title="Output" @@ -246,7 +246,7 @@ awslocal s3tables create-table-bucket --name athena-doc-bucket ``` ```bash -awslocal s3tables create-namespace \ +lstk aws s3tables create-namespace \ --table-bucket-arn arn:aws:s3tables:us-east-1:000000000000:bucket/athena-doc-bucket \ --namespace sales ``` @@ -266,7 +266,7 @@ Register a Glue catalog that federates to S3 Tables using the [`CreateCatalog`]( The catalog name `s3tablescatalog` matches the AWS convention used by Athena, EMR, and Redshift. ```bash -awslocal glue create-catalog \ +lstk aws glue create-catalog \ --name s3tablescatalog \ --catalog-input '{ "FederatedCatalog": { @@ -279,7 +279,7 @@ awslocal glue create-catalog \ You can verify the federated catalog with: ```bash -awslocal glue get-catalogs +lstk aws glue get-catalogs ``` ### Register an Athena data catalog @@ -288,7 +288,7 @@ Register an Athena data catalog that points at a specific table bucket using the The `catalog-id` parameter follows the format `s3tablescatalog/` so that Athena routes queries through the federated catalog path. ```bash -awslocal athena create-data-catalog \ +lstk aws athena create-data-catalog \ --name s3tables-catalog \ --type GLUE \ --parameters "catalog-id=s3tablescatalog/athena-doc-bucket" @@ -297,7 +297,7 @@ awslocal athena create-data-catalog \ Confirm the data catalog status: ```bash -awslocal athena get-data-catalog --name s3tables-catalog +lstk aws athena get-data-catalog --name s3tables-catalog ``` ```bash title="Output" @@ -319,7 +319,7 @@ Once the data catalog is registered, Athena resolves S3 Tables namespaces as dat List the databases exposed by the federated catalog: ```bash -awslocal athena list-databases --catalog-name s3tables-catalog +lstk aws athena list-databases --catalog-name s3tables-catalog ``` ```bash title="Output" @@ -339,7 +339,7 @@ awslocal athena list-databases --catalog-name s3tables-catalog You can also describe a single namespace with [`GetDatabase`](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetDatabase.html): ```bash -awslocal athena get-database \ +lstk aws athena get-database \ --catalog-name s3tables-catalog \ --database-name sales ``` @@ -350,7 +350,7 @@ To query S3 Tables data from Athena, reference the data catalog name in the `Que The `Catalog` field maps to the Athena data catalog you registered, and `Database` maps to the S3 Tables namespace: ```bash -awslocal athena start-query-execution \ +lstk aws athena start-query-execution \ --query-string "CREATE TABLE orders (id int, customer string, amount double) TBLPROPERTIES ('table_type' = 'ICEBERG')" \ --query-execution-context "Catalog=s3tables-catalog,Database=sales" \ --result-configuration "OutputLocation=s3://athena-doc-output/results/" @@ -359,14 +359,14 @@ awslocal athena start-query-execution \ Insert and read data using the same `QueryExecutionContext`: ```bash -awslocal athena start-query-execution \ +lstk aws athena start-query-execution \ --query-string "INSERT INTO orders VALUES (1, 'alice', 100.0), (2, 'bob', 250.5)" \ --query-execution-context "Catalog=s3tables-catalog,Database=sales" \ --result-configuration "OutputLocation=s3://athena-doc-output/results/" ``` ```bash -awslocal athena start-query-execution \ +lstk aws athena start-query-execution \ --query-string "SELECT * FROM orders ORDER BY id" \ --query-execution-context "Catalog=s3tables-catalog,Database=sales" \ --result-configuration "OutputLocation=s3://athena-doc-output/results/" diff --git a/src/content/docs/aws/services/autoscaling.mdx b/src/content/docs/aws/services/autoscaling.mdx index d96e0bcd9..4dfcf143e 100644 --- a/src/content/docs/aws/services/autoscaling.mdx +++ b/src/content/docs/aws/services/autoscaling.mdx @@ -16,7 +16,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Auto Scaling and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Auto Scaling and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how you can create a launch template, an Auto Scaling group, and attach an instance to the Auto Scaling group using the AWS CLI. @@ -27,7 +27,7 @@ You can create a launch template that defines the launch configuration for the i Run the following command to create a launch template: ```bash -awslocal ec2 create-launch-template \ +lstk aws ec2 create-launch-template \ --launch-template-name my-template-for-auto-scaling \ --version-description version1 \ --launch-template-data '{"ImageId":"ami-ff0fea8310f3","InstanceType":"t2.micro"}' @@ -53,14 +53,14 @@ Before creating an Auto Scaling group, you need to fetch the subnet ID. Run the following command to describe the subnets: ```bash -awslocal ec2 describe-subnets --output text --query Subnets[0].SubnetId +lstk aws ec2 describe-subnets --output text --query Subnets[0].SubnetId ``` Copy the subnet ID from the output and use it to create the Auto Scaling group. Run the following command to create an Auto Scaling group using the [`CreateAutoScalingGroup`](https://docs.aws.amazon.com/autoscaling/ec2/APIReference/API_CreateAutoScalingGroup.html) API: ```bash -awslocal autoscaling create-auto-scaling-group \ +lstk aws autoscaling create-auto-scaling-group \ --auto-scaling-group-name my-asg \ --launch-template LaunchTemplateId=lt-5ccdf1a84f178ba44 \ --min-size 1 \ @@ -74,7 +74,7 @@ You can describe the Auto Scaling group using the [`DescribeAutoScalingGroups`]( Run the following command to describe the Auto Scaling group: ```bash -awslocal autoscaling describe-auto-scaling-groups +lstk aws autoscaling describe-auto-scaling-groups ``` ```bash title="Output" @@ -117,7 +117,7 @@ Before that, create an EC2 instance using the [`RunInstances`](https://docs.aws. Run the following command to create an EC2 instance locally: ```bash -awslocal ec2 run-instances \ +lstk aws ec2 run-instances \ --image-id ami-ff0fea8310f3 --count 1 ``` @@ -125,7 +125,7 @@ Fetch the instance ID from the output and use it to attach the instance to the A Run the following command to attach the instance to the Auto Scaling group: ```bash -awslocal autoscaling attach-instances \ +lstk aws autoscaling attach-instances \ --instance-ids i-0d678c4ecf6018dde \ --auto-scaling-group-name my-asg ``` diff --git a/src/content/docs/aws/services/backup.mdx b/src/content/docs/aws/services/backup.mdx index 6c68b0f6a..d3ef5cec8 100644 --- a/src/content/docs/aws/services/backup.mdx +++ b/src/content/docs/aws/services/backup.mdx @@ -19,7 +19,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Backup and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Backup and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a backup job and specify a set of resources to the backup plan name and backup rules with the AWS CLI. @@ -30,7 +30,7 @@ You can create a backup vault which acts as a logical container where backups ar Run the following command to create a backup vault named `my-vault`: ```bash -awslocal backup create-backup-vault \ +lstk aws backup create-backup-vault \ --backup-vault-name primary ``` @@ -73,7 +73,7 @@ You can use the [`CreateBackupPlan`](https://docs.aws.amazon.com/aws-backup/late Run the following command to create a backup plan: ```bash -awslocal backup create-backup-plan \ +lstk aws backup create-backup-plan \ --backup-plan file://backup-plan.json ``` @@ -109,7 +109,7 @@ You can use the [`CreateBackupSelection`](https://docs.aws.amazon.com/aws-backup Run the following command to create a backup selection: ```bash -awslocal backup create-backup-selection \ +lstk aws backup create-backup-selection \ --backup-plan-id 9337aba3 \ --backup-selection file://backup-plan-resources.json ``` diff --git a/src/content/docs/aws/services/batch.mdx b/src/content/docs/aws/services/batch.mdx index 6d85d2aba..64a814e21 100644 --- a/src/content/docs/aws/services/batch.mdx +++ b/src/content/docs/aws/services/batch.mdx @@ -19,7 +19,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to AWS Batch and assumes basic knowledge of the AWS CLI and our `awslocal` wrapper script. +This guide is designed for users new to AWS Batch and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how you create and run a Batch job by following these steps: @@ -39,7 +39,7 @@ LocalStack requires the role to exist with a valid trust policy. When [enforcing Run the following command to create a role for ECS task execution: ```bash -awslocal iam create-role \ +lstk aws iam create-role \ --role-name myrole \ --assume-role-policy-document '{ "Version": "2025-10-17", @@ -58,7 +58,7 @@ awslocal iam create-role \ Then attach the ECS task execution policy: ```bash -awslocal iam attach-role-policy \ +lstk aws iam attach-role-policy \ --role-name myrole \ --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy ``` @@ -71,7 +71,7 @@ You can use the [`CreateComputeEnvironment`](https://docs.aws.amazon.com/cli/lat Run the following command using the role ARN above (arn:aws:iam::000000000000:role/myrole) to create a managed compute environment with FARGATE: ```bash -awslocal batch create-compute-environment \ +lstk aws batch create-compute-environment \ --compute-environment-name myenv \ --type MANAGED \ --state ENABLED \ @@ -91,7 +91,7 @@ You can fetch the ARN using the [`DescribeComputeEnvironments`](https://docs.aws Run the following command to fetch the ARN of the compute environment: ```bash -awslocal batch describe-compute-environments --compute-environments myenv +lstk aws batch describe-compute-environments --compute-environments myenv ``` ```bash title="Output" @@ -115,7 +115,7 @@ You can use the ARN to create the job queue using [`CreateJobQueue`](https://doc Run the following command to create the job queue: ```bash -awslocal batch create-job-queue \ +lstk aws batch create-job-queue \ --job-queue-name myqueue \ --priority 1 \ --compute-environment-order order=0,computeEnvironment=arn:aws:batch:us-east-1:000000000000:compute-environment/myenv \ @@ -130,7 +130,7 @@ Run the following command to create the job definition using the [`RegisterJobDe ```bash -awslocal batch register-job-definition \ +lstk aws batch register-job-definition \ --job-definition-name myjobdefn \ --type container \ --platform-capabilities FARGATE \ @@ -153,7 +153,7 @@ If you want to pass arguments to the command as [parameters](https://docs.aws.am This allows the dynamic passing of values at runtime for specific job definitions. ```bash -awslocal batch register-job-definition \ +lstk aws batch register-job-definition \ --job-definition-name myjobdefn \ --type container \ --parameters '{"time":"10"}' \ @@ -181,7 +181,7 @@ This command simulates work being done in the container. Run the following command to submit a job to the job queue using the [`SubmitJob`](https://docs.aws.amazon.com/cli/latest/reference/batch/submit-job.html) API: ```bash -awslocal batch submit-job \ +lstk aws batch submit-job \ --job-name myjob \ --job-queue myqueue \ --job-definition myjobdefn \ @@ -198,7 +198,7 @@ MNP jobs run on EC2-backed compute environments only. Fargate is not supported. To run one, register a job definition with `--type multinode` and a `nodeProperties` object that sets the main node, the number of nodes, and a container per node range: ```bash -awslocal batch register-job-definition \ +lstk aws batch register-job-definition \ --job-definition-name mnp-jobdefn \ --type multinode \ --node-properties '{ @@ -223,7 +223,7 @@ awslocal batch register-job-definition \ Then submit it to an EC2-backed queue: ```bash -awslocal batch submit-job \ +lstk aws batch submit-job \ --job-name mnp-job \ --job-queue mnp-queue \ --job-definition mnp-jobdefn @@ -232,7 +232,7 @@ awslocal batch submit-job \ The submitted job is the parent. Each node is addressable as a child job using the `#` notation, which you can inspect with `describe-jobs`: ```bash -awslocal batch describe-jobs --jobs "#0" "#1" +lstk aws batch describe-jobs --jobs "#0" "#1" ``` Each node also receives additional [environment variables](#environment-variables), such as `AWS_BATCH_JOB_NODE_INDEX` and `AWS_BATCH_JOB_MAIN_NODE_PRIVATE_IPV4_ADDRESS`, that let the nodes coordinate. diff --git a/src/content/docs/aws/services/bedrock.mdx b/src/content/docs/aws/services/bedrock.mdx index aecb1eaac..ac883afe2 100644 --- a/src/content/docs/aws/services/bedrock.mdx +++ b/src/content/docs/aws/services/bedrock.mdx @@ -16,7 +16,7 @@ The supported APIs are available on the API coverage section for [Bedrock](#api- ## Getting started -This guide is designed for users new to AWS Bedrock and assumes basic knowledge of the AWS CLI and our `awslocal` wrapper script. +This guide is designed for users new to AWS Bedrock and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method with or without pre-warming the Bedrock engine. We will demonstrate how to use Bedrock by following these steps: @@ -49,7 +49,7 @@ You can define the used model with `DEFAULT_BEDROCK_MODEL` Run the following command: ```bash -awslocal bedrock list-foundation-models +lstk aws bedrock list-foundation-models ``` ### Invoke a model @@ -61,7 +61,7 @@ However, the actual model will be defined by the `DEFAULT_BEDROCK_MODEL` environ Run the following command: ```bash -awslocal bedrock-runtime invoke-model \ +lstk aws bedrock-runtime invoke-model \ --model-id "meta.llama3-8b-instruct-v1:0" \ --body '{ "prompt": "<|begin_of_text|><|start_header_id|>user<|end_header_id|>\nSay Hello!\n<|eot_id|>\n<|start_header_id|>assistant<|end_header_id|>", @@ -80,7 +80,7 @@ You can specify both system prompts and user messages. Run the following command: ```bash -awslocal bedrock-runtime converse \ +lstk aws bedrock-runtime converse \ --model-id "meta.llama3-8b-instruct-v1:0" \ --messages '[{ "role": "user", @@ -108,15 +108,15 @@ First, you need to create a `JSONL` file named `batch_input.jsonl` that contains Then, you need to define buckets for the input as well as the output and upload the file in the input bucket: ```bash -awslocal s3 mb s3://in-bucket -awslocal s3 cp batch_input.jsonl s3://in-bucket -awslocal s3 mb s3://out-bucket +lstk aws s3 mb s3://in-bucket +lstk aws s3 cp batch_input.jsonl s3://in-bucket +lstk aws s3 mb s3://out-bucket ``` Afterwards you can run the invocation job like this: ```bash -awslocal bedrock create-model-invocation-job \ +lstk aws bedrock create-model-invocation-job \ --job-name "my-batch-job" \ --model-id "mistral.mistral-small-2402-v1:0" \ --role-arn "arn:aws:iam::123456789012:role/MyBatchInferenceRole" \ @@ -143,14 +143,14 @@ LocalStack will pull the model from Ollama and use it for emulation. For example, to use the Mistral model, set the environment variable while starting LocalStack: ```bash -DEFAULT_BEDROCK_MODEL=mistral localstack start +LOCALSTACK_DEFAULT_BEDROCK_MODEL=mistral lstk start ``` You can also define models directly in the request, by setting the `model-id` parameter to `ollama.`. For example, if you want to access `deepseek-r1`, you can do it like this: ```bash -awslocal bedrock-runtime converse \ +lstk aws bedrock-runtime converse \ --model-id "ollama.deepseek-r1" \ --messages '[{ "role": "user", diff --git a/src/content/docs/aws/services/ce.mdx b/src/content/docs/aws/services/ce.mdx index b33762874..1c195737e 100644 --- a/src/content/docs/aws/services/ce.mdx +++ b/src/content/docs/aws/services/ce.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Cost Explorer and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Cost Explorer and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to mock the Cost Explorer APIs with the AWS CLI. @@ -28,7 +28,7 @@ You can create a Cost Category definition using the [`CreateCostCategoryDefiniti The following example creates a Cost Category definition using an empty rule condition of type "REGULAR": ```bash -awslocal ce create-cost-category-definition --name test \ +lstk aws ce create-cost-category-definition --name test \ --rule-version "CostCategoryExpression.v1" --rules '[{"Value": "test", "Rule": {}, "Type": "REGULAR"}]' ``` @@ -42,7 +42,7 @@ You can describe the Cost Category definition using the [`DescribeCostCategoryDe Run the following command: ```bash -awslocal ce describe-cost-category-definition \ +lstk aws ce describe-cost-category-definition \ --cost-category-arn arn:aws:ce::000000000000:costcategory/test ``` @@ -69,7 +69,7 @@ You can add an alert subscription to a cost anomaly detection monitor to define The following example creates a cost anomaly subscription: ```bash -awslocal ce create-anomaly-subscription --anomaly-subscription '{ +lstk aws ce create-anomaly-subscription --anomaly-subscription '{ "AccountId": "12345", "SubscriptionName": "sub1", "Frequency": "DAILY", @@ -89,7 +89,7 @@ You can retrieve the cost anomaly subscriptions using the [`GetAnomalySubscripti Run the following command: ```bash -awslocal ce get-anomaly-subscriptions +lstk aws ce get-anomaly-subscriptions ``` ```bash title="Output" @@ -114,7 +114,7 @@ You can create a new cost anomaly detection subscription with the requested type The following example creates a cost anomaly monitor: ```bash -awslocal ce create-anomaly-monitor --anomaly-monitor '{ +lstk aws ce create-anomaly-monitor --anomaly-monitor '{ "MonitorName": "mon5463", "MonitorType": "DIMENSIONAL" }' @@ -130,7 +130,7 @@ You can retrieve the cost anomaly monitors using the [`GetAnomalyMonitors`](http Run the following command: ```bash -awslocal ce get-anomaly-monitors +lstk aws ce get-anomaly-monitors ``` ```bash title="Output" diff --git a/src/content/docs/aws/services/cloudcontrol.mdx b/src/content/docs/aws/services/cloudcontrol.mdx index 7ed21379f..13688a835 100644 --- a/src/content/docs/aws/services/cloudcontrol.mdx +++ b/src/content/docs/aws/services/cloudcontrol.mdx @@ -16,7 +16,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Cloud Control and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Cloud Control and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to get and list resources using the Cloud Control API. @@ -28,13 +28,13 @@ You can list resources using the [`ListResources`](https://docs.aws.amazon.com/c Create an S3 bucket using the following command: ```bash -awslocal s3 mb s3://my-bucket +lstk aws s3 mb s3://my-bucket ``` List the resources using the following command: ```bash -awslocal cloudcontrol list-resources --type-name AWS::S3::Bucket +lstk aws cloudcontrol list-resources --type-name AWS::S3::Bucket ``` You should see the S3 bucket in the output. @@ -56,7 +56,7 @@ You should see the S3 bucket in the output. You can get a resource using the [`GetResource`](https://docs.aws.amazon.com/cloudcontrolapi/latest/APIReference/API_GetResource.html) API. ```bash -awslocal cloudcontrol get-resource --type-name AWS::S3::Bucket --identifier my-bucket +lstk aws cloudcontrol get-resource --type-name AWS::S3::Bucket --identifier my-bucket ``` ```bash title="Output" diff --git a/src/content/docs/aws/services/cloudformation.mdx b/src/content/docs/aws/services/cloudformation.mdx index 4e1fd6fe4..4f340fb1a 100644 --- a/src/content/docs/aws/services/cloudformation.mdx +++ b/src/content/docs/aws/services/cloudformation.mdx @@ -56,7 +56,7 @@ The [API Coverage section](#api-coverage) and [feature coverage](#feature-covera ## Getting started -This guide is designed for users new to CloudFormation and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to CloudFormation and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to deploy a simple CloudFormation stack consisting of a single S3 Bucket with the AWS CLI. @@ -100,7 +100,7 @@ The `deploy` command creates and updates CloudFormation stacks. Run the following command to deploy the stack: ```bash -awslocal cloudformation deploy \ +lstk aws cloudformation deploy \ --stack-name cfn-quickstart-stack \ --template-file "./cfn-quickstart-stack.yaml" ``` @@ -109,7 +109,7 @@ You can verify that the stack was created successfully by listing the S3 buckets Run the following command to list the buckets: ```bash -awslocal s3api list-buckets +lstk aws s3api list-buckets ``` ### Delete the CloudFormation Stack @@ -118,7 +118,7 @@ You can delete the CloudFormation stack using the [`delete-stack`](https://docs. Run the following command to delete the stack along with all the resources created by the stack: ```bash -awslocal cloudformation delete-stack \ +lstk aws cloudformation delete-stack \ --stack-name cfn-quickstart-stack ``` @@ -134,7 +134,7 @@ When a private extension is activated, LocalStack deploys and invokes the embedd Build and package your extension using the CloudFormation CLI, then upload the package to S3 and register the type: ```bash -awslocal cloudformation register-type \ +lstk aws cloudformation register-type \ --type RESOURCE \ --type-name MyOrg::MyService::MyResource \ --schema-handler-package s3://my-bucket/my-extension.zip diff --git a/src/content/docs/aws/services/cloudfront.mdx b/src/content/docs/aws/services/cloudfront.mdx index 38c7321d2..799a31e7b 100644 --- a/src/content/docs/aws/services/cloudfront.mdx +++ b/src/content/docs/aws/services/cloudfront.mdx @@ -21,7 +21,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started This guide is intended for users who wish to get more acquainted with CloudFront over LocalStack. -It assumes you have basic knowledge of the AWS CLI (and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script). +It assumes you have basic knowledge of the AWS CLI (and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command). Start your LocalStack container using your preferred method. We will demonstrate how you can create an S3 bucket, put a text file named `hello.txt` to the bucket, and then create a CloudFront distribution which makes the file accessible via a `https://abc123.cloudfront.net/hello.txt` proxy URL (where `abc123` is a placeholder for the real distribution ID). @@ -29,21 +29,21 @@ We will demonstrate how you can create an S3 bucket, put a text file named `hell To get started, create an S3 bucket using the `mb` command: ```bash -awslocal s3 mb s3://abc123 +lstk aws s3 mb s3://abc123 ``` You can now go ahead, create a new text file named `hello.txt` and upload it to the bucket: ```bash echo 'Hello World' > /tmp/hello.txt -awslocal s3 cp /tmp/hello.txt s3://abc123/hello.txt --acl public-read +lstk aws s3 cp /tmp/hello.txt s3://abc123/hello.txt --acl public-read ``` After uploading the file to S3, you can create a CloudFront distribution using the [`CreateDistribution`](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_CreateDistribution.html) API call. Run the following command to create a distribution with the default settings: ```bash -domain=$(awslocal cloudfront create-distribution \ +domain=$(lstk aws cloudfront create-distribution \ --origin-domain-name abc123.s3.amazonaws.com | jq -r '.Distribution.DomainName') curl -k https://$domain/hello.txt ``` diff --git a/src/content/docs/aws/services/cloudtrail.mdx b/src/content/docs/aws/services/cloudtrail.mdx index 8c4c69829..dee9146cd 100644 --- a/src/content/docs/aws/services/cloudtrail.mdx +++ b/src/content/docs/aws/services/cloudtrail.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to CloudTrail and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to CloudTrail and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to enable S3 object logging to CloudTrail using AWS CLI. @@ -28,7 +28,7 @@ Before you create a trail, you need to create an S3 bucket where CloudTrail can You can use the [`mb`](https://docs.aws.amazon.com/cli/latest/reference/s3/mb.html) command to create a bucket: ```bash -awslocal s3 mb s3://my-bucket +lstk aws s3 mb s3://my-bucket ``` ### Create a trail @@ -38,7 +38,7 @@ You can use the [`CreateTrail`](https://docs.aws.amazon.com/awscloudtrail/latest Run the following command to create a trail: ```bash -awslocal cloudtrail create-trail \ +lstk aws cloudtrail create-trail \ --name MyTrail \ --s3-bucket-name my-bucket ``` @@ -50,7 +50,7 @@ You can use the [`StartLogging`](https://docs.aws.amazon.com/awscloudtrail/lates Run the following command to enable logging: ```bash -awslocal cloudtrail start-logging --name MyTrail +lstk aws cloudtrail start-logging --name MyTrail ``` You can further configure event selectors for the trail. @@ -59,7 +59,7 @@ You can use the [`PutEventSelectors`](https://docs.aws.amazon.com/awscloudtrail/ Run the following command to configure event selectors: ```bash -awslocal cloudtrail put-event-selectors \ +lstk aws cloudtrail put-event-selectors \ --trail-name MyTrail \ --event-selectors '[{"ReadWriteType": "All", "IncludeManagementEvents":true, "DataResources": [{"Type": "AWS::S3::Object", "Values": ["arn:aws:s3:::my-bucket/"]}]}]' ``` @@ -68,7 +68,7 @@ You can verify if your configuration is correct by using the [`GetEventSelectors Run the following command to verify your configuration: ```bash -awslocal cloudtrail get-event-selectors \ +lstk aws cloudtrail get-event-selectors \ --trail-name MyTrail ``` @@ -99,8 +99,8 @@ You can use the [`cp`](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.ht ```bash echo "hello world" > /tmp/hello-world -awslocal s3 cp /tmp/hello-world s3://my-bucket/hello-world -awslocal s3 ls s3://my-bucket +lstk aws s3 cp /tmp/hello-world s3://my-bucket/hello-world +lstk aws s3 ls s3://my-bucket ``` You can verify that the object was created in the S3 bucket. @@ -108,7 +108,7 @@ You can also verify that the object level event was logged by CloudTrail using t Run the following command to verify the event: ```bash -awslocal cloudtrail lookup-events \ +lstk aws cloudtrail lookup-events \ --lookup-attributes AttributeKey=EventName,AttributeValue=PutObject \ --max-results 1 ``` diff --git a/src/content/docs/aws/services/cloudwatch.mdx b/src/content/docs/aws/services/cloudwatch.mdx index 1a6a62398..2e3355c54 100644 --- a/src/content/docs/aws/services/cloudwatch.mdx +++ b/src/content/docs/aws/services/cloudwatch.mdx @@ -18,7 +18,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to CloudWatch and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to CloudWatch and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method and deploy your Lambda functions that will generate some logs. You can get the name for your Lambda Functions using the [`ListFunctions`](https://docs.aws.amazon.com/lambda/latest/dg/API_ListFunctions.html) API. @@ -27,7 +27,7 @@ Fetch the Log Groups using the [`DescribeLogGroups`](https://docs.aws.amazon.com Run the following command to get the Log Group name: ```bash -awslocal logs describe-log-groups +lstk aws logs describe-log-groups ``` ```bash title="Output" @@ -55,7 +55,7 @@ Get the log streams for the Log Group using the [`DescribeLogStreams`](https://d Run the following command to get the Log Stream name: ```bash -awslocal logs describe-log-streams \ +lstk aws logs describe-log-streams \ --log-group-name /aws/lambda/serverless-local-hello ``` @@ -80,7 +80,7 @@ You can now fetch the log events using the [`GetLogEvents`](https://docs.aws.ama Run the following command to get the logs: ```bash -awslocal logs get-log-events \ +lstk aws logs get-log-events \ --log-group-name '/aws/lambda/serverless-local-hello' --log-stream-name '2023/05/02/[$LATEST]853a59d0767cfaf10d6b29a6790d8b03' ``` @@ -125,10 +125,10 @@ These features enable you to define and evaluate alarms based on various statist Metric alarms in CloudWatch allow you to evaluate the state of a metric by analyzing its data points over a specified period. With metric alarms, you can create customized thresholds and define actions based on the metric's behavior. -To get started with creating an alarm in LocalStack using the `awslocal` integration, use the following command: +To get started with creating an alarm in LocalStack using the `lstk aws` integration, use the following command: ```bash -awslocal cloudwatch put-metric-alarm \ +lstk aws cloudwatch put-metric-alarm \ --alarm-name my-alarm \ --metric-name Orders \ --namespace test \ @@ -143,13 +143,13 @@ awslocal cloudwatch put-metric-alarm \ To monitor the status of the alarm, open a separate terminal and execute the following command: ```bash -watch "awslocal cloudwatch describe-alarms --alarm-names my-alarm | jq '.MetricAlarms[0].StateValue'" +watch "lstk aws cloudwatch describe-alarms --alarm-names my-alarm | jq '.MetricAlarms[0].StateValue'" ``` Afterward, you can add some data that will cause a breach and set the `metric-alarm` state to **ALARM** using the following command: ```bash -awslocal cloudwatch put-metric-data \ +lstk aws cloudwatch put-metric-data \ --namespace test \ --metric-data '[{"MetricName": "Orders", "Value": -1}]' ``` @@ -167,7 +167,7 @@ Here's an example demonstrating how to set up an alarm that sends a message to t Make sure to replace `` with the valid ARN of an existing SNS topic. ```bash -awslocal cloudwatch put-metric-alarm \ +lstk aws cloudwatch put-metric-alarm \ --alarm-name my-alarm \ --metric-name Orders \ --namespace test \ diff --git a/src/content/docs/aws/services/codeartifact.mdx b/src/content/docs/aws/services/codeartifact.mdx index 5e6befedd..663b0892f 100644 --- a/src/content/docs/aws/services/codeartifact.mdx +++ b/src/content/docs/aws/services/codeartifact.mdx @@ -19,9 +19,9 @@ It also has full support to create and use NPM repositories. ## Getting Started -This guide will help you create a domain, repository, and manage package publishing workflows using the `awslocal` CLI. +This guide will help you create a domain, repository, and manage package publishing workflows using the `lstk aws` command. -Basic knowledge of the AWS CLI and the [`awslocal`](https://github.com/localstack/awscli-local) wrapper is expected. +Basic knowledge of the AWS CLI and the [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command is expected. Start LocalStack using your preferred method. @@ -32,7 +32,7 @@ Domains are the top-level containers for repositories in CodeArtifact. Create a domain with the [`CreateDomain`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_CreateDomain.html) API. ```bash -awslocal codeartifact create-domain --domain demo-domain +lstk aws codeartifact create-domain --domain demo-domain ``` ```json title="Output" @@ -52,7 +52,7 @@ awslocal codeartifact create-domain --domain demo-domain You can use the [`DescribeDomain`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DescribeDomain.html), [`UpdateDomain`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_UpdateDomain.html), and [`DeleteDomain`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DeleteDomain.html) APIs for domain management. ```bash -awslocal codeartifact describe-domain --domain demo-domain +lstk aws codeartifact describe-domain --domain demo-domain ``` ```json title="Output" @@ -72,7 +72,7 @@ awslocal codeartifact describe-domain --domain demo-domain You can list all domains using the [`ListDomains`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_ListDomains.html) API. ```bash -awslocal codeartifact list-domains +lstk aws codeartifact list-domains ``` ```json title="Output" @@ -96,7 +96,7 @@ Repositories store packages and are associated with a domain. Create a repository using the [`CreateRepository`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_CreateRepository.html) API. ```bash -awslocal codeartifact create-repository --domain demo-domain \ +lstk aws codeartifact create-repository --domain demo-domain \ --repository demo-repo ``` @@ -118,7 +118,7 @@ awslocal codeartifact create-repository --domain demo-domain \ You can use the [`DescribeRepository`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DescribeRepository.html), [`UpdateRepository`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_UpdateRepository.html), and [`DeleteRepository`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DeleteRepository.html) APIs to manage repositories. ```bash -awslocal codeartifact describe-repository --domain demo-domain \ +lstk aws codeartifact describe-repository --domain demo-domain \ --repository demo-repo ``` @@ -140,7 +140,7 @@ awslocal codeartifact describe-repository --domain demo-domain \ Use the [`ListRepositories`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_ListRepositories.html) API to view all of the repositories. ```bash -awslocal codeartifact list-repositories +lstk aws codeartifact list-repositories ``` ```json title="Output" @@ -161,7 +161,7 @@ awslocal codeartifact list-repositories Otherwise, list repositories in a specific domain using the [`ListRepositoriesInDomain`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_ListRepositoriesInDomain.html) API. ```bash -awslocal codeartifact list-repositories-in-domain --domain demo-domain +lstk aws codeartifact list-repositories-in-domain --domain demo-domain ``` ```json title="Output" @@ -191,7 +191,7 @@ This makes it possible to consume open-source dependencies used by your applicat Repositories can be associated with external connections using [AssociateExternalConnection](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_AssociateExternalConnection.html) and [DisassociateExternalConnection](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DisassociateExternalConnection.html) APIs. ```bash -awslocal codeartifact associate-external-connection --domain demo-domain \ +lstk aws codeartifact associate-external-connection --domain demo-domain \ --repository demo-repo \ --external-connection "public:npmjs" ``` @@ -220,7 +220,7 @@ awslocal codeartifact associate-external-connection --domain demo-domain \ Alternatively, repositories can be configured with upstream repositories using the `upstreams` property of [CreateRepository](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_CreateRepository.html) and [UpdateRepository](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_UpdateRepository.html). ```bash -awslocal codeartifact create-repository --domain demo-domain \ +lstk aws codeartifact create-repository --domain demo-domain \ --repository demo-repo2 \ --upstreams repositoryName=demo-repo ``` @@ -252,10 +252,10 @@ Please note, a repository can have one or more upstream repositories, or an exte ### Configuring npm with the login command -Use the `awslocal codeartifact login` command to fetch credentials for use with npm. +Use the `lstk aws codeartifact login` command to fetch credentials for use with npm. ```bash -awslocal codeartifact login --tool npm --domain demo-domain --repository demo-repo +lstk aws codeartifact login --tool npm --domain demo-domain --repository demo-repo ``` This command makes the following changes to your `~/.npmrc` file: @@ -269,20 +269,20 @@ For more information about the authorization token created with the login comman ### Configuring npm manually -You can configure npm with your CodeArtifact repository without the `awslocal codeartifact login` command by manually updating the npm configuration. +You can configure npm with your CodeArtifact repository without the `lstk aws codeartifact login` command by manually updating the npm configuration. 1. In a command line, fetch a CodeArtifact authorization token and store it in an environment variable. npm will use this token to authenticate with your CodeArtifact repository. ```bash - export CODEARTIFACT_AUTH_TOKEN=$(awslocal codeartifact get-authorization-token --domain demo-domain --query authorizationToken --output text) + export CODEARTIFACT_AUTH_TOKEN=$(lstk aws codeartifact get-authorization-token --domain demo-domain --query authorizationToken --output text) ``` 2. Get your CodeArtifact repository's endpoint by running the following command. Your repository endpoint is used to point npm to your repository to install or publish packages. ```bash - awslocal codeartifact get-repository-endpoint --domain demo-domain --repository demo-repo --format npm --output text + lstk aws codeartifact get-repository-endpoint --domain demo-domain --repository demo-repo --format npm --output text ``` The following URL is an example repository endpoint. diff --git a/src/content/docs/aws/services/codebuild.mdx b/src/content/docs/aws/services/codebuild.mdx index 45a7438e3..8a892acf7 100644 --- a/src/content/docs/aws/services/codebuild.mdx +++ b/src/content/docs/aws/services/codebuild.mdx @@ -22,7 +22,7 @@ AWS CodeBuild emulation is powered by the [AWS CodeBuild agent](https://docs.aws This tutorial will show you how to use AWS CodeBuild to test and build a deployable version of a Java executable. -It assumes basic knowledge of the [`awslocal`](https://github.com/localstack/awscli-local) wrapper, Apache Maven, and Java. +It assumes basic knowledge of the [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command, Apache Maven, and Java. ### Create the source code @@ -178,8 +178,8 @@ Now we have to create two S3 buckets: Create the buckets with the following commands: ```bash -awslocal s3 mb s3://codebuild-demo-input -awslocal s3 mb s3://codebuild-demo-output +lstk aws s3 mb s3://codebuild-demo-input +lstk aws s3 mb s3://codebuild-demo-output ``` Finally, zip the content of the source code directory and upload it to the created source bucket. @@ -192,7 +192,7 @@ zip -r MessageUtil.zip Then, upload `MessageUtil.zip` to the `codebuild-demo-input` bucket with the following command: ```bash -awslocal s3 cp MessageUtil.zip s3://codebuild-demo-input +lstk aws s3 cp MessageUtil.zip s3://codebuild-demo-input ``` ### Configuring IAM @@ -218,7 +218,7 @@ Create a `create-role.json` file with following content: Then, run the following command to create the necessary IAM role: ```bash -awslocal iam create-role --role-name CodeBuildServiceRole --assume-role-policy-document file://create-role.json +lstk aws iam create-role --role-name CodeBuildServiceRole --assume-role-policy-document file://create-role.json ``` From the command's response, keep note of the role ARN: @@ -282,7 +282,7 @@ Create a `put-role-policy.json` file with the following content: Finally, assign the policy to the role with the following command: ```bash -awslocal put-role-policy \ +lstk aws put-role-policy \ --role-name CodeBuildServiceRole \ --policy-name CodeBuildServiceRolePolicy \ --policy-document file://put-role-policy.json @@ -296,7 +296,7 @@ You can use the CLI to generate the skeleton of the `CreateBuild` request, which Save the output of the following command to a file named `create-project.json`. ```bash -awslocal codebuild create-project --generate-cli-skeleton +lstk aws codebuild create-project --generate-cli-skeleton ``` From the generated file, change the source and the artifact location to match the S3 bucket names you just created. @@ -325,7 +325,7 @@ Similarly, fill in the ARN of the CodeBuild service role. Now create the project with the following command: ```bash -awslocal codebuild create-project --cli-input-json file://create-project.json +lstk aws codebuild create-project --cli-input-json file://create-project.json ``` You have now created a CodeBuild project called `codebuild-demo-project` that uses the S3 buckets you just created as source and artifact. @@ -340,7 +340,7 @@ See the [Build Environments](#build-environments) section for more details. In this final step, you can now execute your build with the following command: ```bash -awslocal codebuild start-build --project-name codebuild-demo-project +lstk aws codebuild start-build --project-name codebuild-demo-project ``` Make note of the `id` information given in output, since it can be used to query the status of the build. @@ -350,7 +350,7 @@ This container will be responsible to start a Docker compose stack that executes As said, you can inspect the status of the build with the following command: ```bash -awslocal codebuild batch-get-builds --ids +lstk aws codebuild batch-get-builds --ids ``` The command returns a list of builds. @@ -365,7 +365,7 @@ Currently, it reports only the final status of the build. Once the build is completed, you can verify that the JAR artifact has been uploaded to the correct S3 bucket with the following command: ```bash -awslocal s3 ls s3://codebuild-demo-output +lstk aws s3 ls s3://codebuild-demo-output ``` diff --git a/src/content/docs/aws/services/codecommit.mdx b/src/content/docs/aws/services/codecommit.mdx index fc434b1da..eff9e018c 100644 --- a/src/content/docs/aws/services/codecommit.mdx +++ b/src/content/docs/aws/services/codecommit.mdx @@ -19,7 +19,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to CodeCommit and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to CodeCommit and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how you can create a CodeCommit repository, clone a repository, and push a commit to the repository. @@ -32,7 +32,7 @@ You need to specify the repository name, repository description, and tags. Run the following command to create a new repository named `localstack-repo`: ```bash -awslocal codecommit create-repository \ +lstk aws codecommit create-repository \ --repository-name localstack-repo \ --repository-description "A demo repository to showcase LocalStack's CodeCommit" \ --tags Team=LocalStack diff --git a/src/content/docs/aws/services/codeconnections.mdx b/src/content/docs/aws/services/codeconnections.mdx index e5b02acff..e698871a5 100644 --- a/src/content/docs/aws/services/codeconnections.mdx +++ b/src/content/docs/aws/services/codeconnections.mdx @@ -20,7 +20,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to CodeConnections and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to CodeConnections and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a connection to a code repository using the CodeConnections API. @@ -30,7 +30,7 @@ We will demonstrate how to create a connection to a code repository using the Co You can create a connection to a code repository using the [`CreateConnection`](https://docs.aws.amazon.com/codeconnections/latest/APIReference/API_CreateConnection.html) API. ```bash -awslocal codeconnections create-connection \ +lstk aws codeconnections create-connection \ --connection-name my-connection ``` @@ -46,7 +46,7 @@ You should see the connection in the output. You can list connections using the [`ListConnections`](https://docs.aws.amazon.com/codeconnections/latest/APIReference/API_ListConnections.html) API. ```bash -awslocal codeconnections list-connections +lstk aws codeconnections list-connections ``` ```bash title="Output" @@ -68,7 +68,7 @@ awslocal codeconnections list-connections You can get a connection using the [`GetConnection`](https://docs.aws.amazon.com/codeconnections/latest/APIReference/API_GetConnection.html) API. ```bash -awslocal codeconnections get-connection --connection-arn arn:aws:codeconnections:us-east-1:000000000000:connection/023ff7e3 +lstk aws codeconnections get-connection --connection-arn arn:aws:codeconnections:us-east-1:000000000000:connection/023ff7e3 ``` Replace the `connection-arn` with the ARN of the connection you want to get. @@ -90,7 +90,7 @@ Replace the `connection-arn` with the ARN of the connection you want to get. You can delete a connection using the [`DeleteConnection`](https://docs.aws.amazon.com/codeconnections/latest/APIReference/API_DeleteConnection.html) API. ```bash -awslocal codeconnections delete-connection --connection-arn arn:aws:codeconnections:us-east-1:000000000000:connection/023ff7e3 +lstk aws codeconnections delete-connection --connection-arn arn:aws:codeconnections:us-east-1:000000000000:connection/023ff7e3 ``` Replace the `connection-arn` with the ARN of the connection you want to delete. diff --git a/src/content/docs/aws/services/codedeploy.mdx b/src/content/docs/aws/services/codedeploy.mdx index 36f528db2..ca3c10e3b 100644 --- a/src/content/docs/aws/services/codedeploy.mdx +++ b/src/content/docs/aws/services/codedeploy.mdx @@ -19,7 +19,7 @@ The supported operations are listed on the [API Coverage section](#api-coverage) This guide will walk through the process of creating CodeDeploy applications, deployment configuration, deployment groups, and deployments. -Basic knowledge of the AWS CLI and the [`awslocal`](https://github.com/localstack/awscli-local) wrapper is expected. +Basic knowledge of the AWS CLI and the [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command is expected. Start LocalStack using your preferred method. @@ -29,7 +29,7 @@ An application is a CodeDeploy construct that uniquely identifies your targetted Create an application with the [CreateApplication](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_CreateApplication.html) operation: ```bash -awslocal deploy create-application --application-name hello --compute-platform Server +lstk aws deploy create-application --application-name hello --compute-platform Server ``` ```bash title="Output" @@ -41,7 +41,7 @@ awslocal deploy create-application --application-name hello --compute-platform S Make note of the application name, which can be used with other operations such as [GetApplication](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_GetApplication.html), [UpdateApplication](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_UpdateApplication.html) and [DeleteApplication](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_DeleteApplication.html). ```bash -awslocal deploy get-application --application-name hello +lstk aws deploy get-application --application-name hello ``` ```bash title="Output" @@ -58,7 +58,7 @@ awslocal deploy get-application --application-name hello You can list all application using [ListApplications](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_ListApplications.html). ```bash -awslocal deploy list-applications +lstk aws deploy list-applications ``` ```bash title="Output" @@ -76,7 +76,7 @@ A deployment configuration consists of rules for deployment along with success a Create a deployment configuration using [CreateDeploymentConfig](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_CreateDeploymentConfig.html): ```bash -awslocal deploy create-deployment-config --deployment-config-name hello-conf \ +lstk aws deploy create-deployment-config --deployment-config-name hello-conf \ --compute-platform Server \ --minimum-healthy-hosts '{"type": "HOST_COUNT", "value": 1}' ``` @@ -90,7 +90,7 @@ awslocal deploy create-deployment-config --deployment-config-name hello-conf \ [ListDeploymentConfigs](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_ListDeploymentConfigs.html) can be used to list all available configs: ```bash -awslocal deploy list-deployment-configs +lstk aws deploy list-deployment-configs ``` ```bash title="Output" @@ -104,7 +104,7 @@ awslocal deploy list-deployment-configs Use [GetDeploymentConfig](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_GetDeploymentConfig.html) and [DeleteDeploymentConfig](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_DeleteDeploymentConfig.html) to manage deployment configurations. ```bash -awslocal deploy get-deployment-config --deployment-config-name hello-conf +lstk aws deploy get-deployment-config --deployment-config-name hello-conf ``` ```bash title="Output" @@ -135,7 +135,7 @@ Deployment groups can be managed with: Create a deployment group with [CreateDeploymentGroup](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_CreateDeploymentGroup.html): ```bash -awslocal deploy create-deployment-group \ +lstk aws deploy create-deployment-group \ --application-name hello \ --service-role-arn arn:aws:iam::000000000000:role/role \ --deployment-group-name hello-group @@ -150,7 +150,7 @@ awslocal deploy create-deployment-group \ List all deployment groups for an application with [ListDeploymentGroups](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_ListDeploymentGroups.html): ```bash -awslocal deploy list-deployment-groups --application-name hello +lstk aws deploy list-deployment-groups --application-name hello ``` ```bash title="Output" @@ -164,7 +164,7 @@ awslocal deploy list-deployment-groups --application-name hello Get a deployment group with [GetDeploymentGroup](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_GetDeploymentGroup.html): ```bash -awslocal deploy get-deployment-group --application-name hello \ +lstk aws deploy get-deployment-group --application-name hello \ --deployment-group-name hello-group ``` @@ -200,7 +200,7 @@ Operations related to deployment management are: Create a deployment with [CreateDeployment](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_CreateDeployment.html): ```bash -awslocal deploy create-deployment \ +lstk aws deploy create-deployment \ --application-name hello \ --deployment-group-name hello-group \ --revision '{"revisionType": "S3", "s3Location": {"bucket": "placeholder", "key": "placeholder", "bundleType": "tar"}}' @@ -215,7 +215,7 @@ awslocal deploy create-deployment \ List all deployments for an application with [ListDeployments](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_ListDeployments.html): ```bash -awslocal deploy list-deployments +lstk aws deploy list-deployments ``` ```bash title="Output" @@ -229,7 +229,7 @@ awslocal deploy list-deployments Get a deployment with [GetDeployment](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_GetDeployment.html): ```bash -awslocal deploy get-deployment --deployment-id d-TU3TNCSTO +lstk aws deploy get-deployment --deployment-id d-TU3TNCSTO ``` ```bash title="Output" @@ -269,13 +269,13 @@ Furthermore, [ContinueDeployment](https://docs.aws.amazon.com/codedeploy/latest/ Continue a deployment with [ContinueDeployment](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_StopDeployment.html): ```bash -awslocal deploy continue-deployment --deployment-id d-TU3TNCSTO +lstk aws deploy continue-deployment --deployment-id d-TU3TNCSTO ``` Stop a deployment with [StopDeployment](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_StopDeployment.html): ```bash -awslocal deploy stop-deployment --deployment-id d-TU3TNCSTO +lstk aws deploy stop-deployment --deployment-id d-TU3TNCSTO ``` ```bash title="Output" diff --git a/src/content/docs/aws/services/codepipeline.mdx b/src/content/docs/aws/services/codepipeline.mdx index e77dcdeb8..495983240 100644 --- a/src/content/docs/aws/services/codepipeline.mdx +++ b/src/content/docs/aws/services/codepipeline.mdx @@ -18,7 +18,7 @@ The available operations can be found on the [API coverage](#api-coverage) page. ## Getting started In this guide, we will create a simple pipeline that fetches an object from an S3 bucket and uploads it to a different S3 bucket. -It is for users that are new to CodePipeline and have a basic knowledge of the AWS CLI and the [`awslocal`](https://github.com/localstack/awscli-local) wrapper. +It is for users that are new to CodePipeline and have a basic knowledge of the AWS CLI and the [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start LocalStack using your preferred method. @@ -27,15 +27,15 @@ Start LocalStack using your preferred method. Begin by creating the S3 buckets that will serve as the source and target. ```bash -awslocal s3 mb s3://source-bucket -awslocal s3 mb s3://target-bucket +lstk aws s3 mb s3://source-bucket +lstk aws s3 mb s3://target-bucket ``` It is important to note the CodePipeline requires source S3 buckets to have versioning enabled. This can be done using the S3 [`PutBucketVersioning`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketVersioning.html) operation. ```bash -awslocal s3api put-bucket-versioning \ +lstk aws s3api put-bucket-versioning \ --bucket source-bucket \ --versioning-configuration Status=Enabled ``` @@ -44,13 +44,13 @@ Now create a placeholder file that will flow through the pipeline and upload it ```bash echo "Hello LocalStack!" > file -awslocal s3 cp file s3://source-bucket +lstk aws s3 cp file s3://source-bucket ``` Pipelines also require an artifact store, which is also an S3 bucket that is used as intermediate storage. ```bash -awslocal s3 mb s3://artifact-store-bucket +lstk aws s3 mb s3://artifact-store-bucket ``` ### Configure IAM @@ -80,7 +80,7 @@ Create the role and make note of the role ARN: Create the role with the following command: ```bash -awslocal iam create-role --role-name role --assume-role-policy-document file://role.json | jq .Role.Arn +lstk aws iam create-role --role-name role --assume-role-policy-document file://role.json | jq .Role.Arn ``` Now add a permissions policy to this role that permits read and write access to S3. @@ -105,7 +105,7 @@ The permissions in the above example policy are relatively broad. You might want to use a more focused policy for better security on production systems. ```bash -awslocal iam put-role-policy --role-name role --policy-name policy --policy-document file://policy.json +lstk aws iam put-role-policy --role-name role --policy-name policy --policy-document file://policy.json ``` ### Create pipeline @@ -193,7 +193,7 @@ These correspond to the resources we created earlier. Create the pipeline using the following command: ```bash -awslocal codepipeline create-pipeline --pipeline file://./declaration.json +lstk aws codepipeline create-pipeline --pipeline file://./declaration.json ``` ### Verify pipeline execution @@ -204,7 +204,7 @@ The [`CreatePipeline`](https://docs.aws.amazon.com/codepipeline/latest/APIRefere This can be confirmed using: ```bash -awslocal codepipeline list-pipeline-executions --pipeline-name pipeline +lstk aws codepipeline list-pipeline-executions --pipeline-name pipeline ``` ```bash title="Output" @@ -231,7 +231,7 @@ The above pipeline execution was successful. This means that we can retrieve the `output-file` object from the `target-bucket` S3 bucket. ```bash -awslocal s3 cp s3://target-bucket/output-file output-file +lstk aws s3 cp s3://target-bucket/output-file output-file ``` To verify that it is the same file as the original input: @@ -252,7 +252,7 @@ Using the [`ListActionExecutions`](https://docs.aws.amazon.com/codepipeline/late This is useful when debugging the pipeline. ```bash -awslocal codepipeline list-action-executions --pipeline-name pipeline +lstk aws codepipeline list-action-executions --pipeline-name pipeline ``` ```bash title="Output" @@ -354,11 +354,11 @@ Pipelines resources can be [tagged](https://docs.aws.amazon.com/codepipeline/lat Tag the pipeline with the following command: ```bash -awslocal codepipeline tag-resource \ +lstk aws codepipeline tag-resource \ --resource-arn arn:aws:codepipeline:eu-central-1:000000000000:pipeline \ --tags key=purpose,value=tutorial -awslocal codepipeline list-tags-for-resource \ +lstk aws codepipeline list-tags-for-resource \ --resource-arn arn:aws:codepipeline:eu-central-1:000000000000:pipeline ``` @@ -376,7 +376,7 @@ awslocal codepipeline list-tags-for-resource \ Untag the pipeline with the following command: ```bash -awslocal codepipeline untag-resource \ +lstk aws codepipeline untag-resource \ --resource-arn arn:aws:codepipeline:eu-central-1:000000000000:pipeline \ --tag-keys purpose ``` diff --git a/src/content/docs/aws/services/cognito-idp.mdx b/src/content/docs/aws/services/cognito-idp.mdx index 4d7d30a90..ea3f872dc 100644 --- a/src/content/docs/aws/services/cognito-idp.mdx +++ b/src/content/docs/aws/services/cognito-idp.mdx @@ -18,7 +18,7 @@ The supported APIs are available on our [Cognito Identity coverage section](#api ## Getting started -This guide is designed for users new to Cognito and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Cognito and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how you can create a Cognito user pool and client, and then sign up and authenticate a new user in the pool. @@ -29,7 +29,7 @@ To create a user pool, you can use the [`CreateUserPool`](https://docs.aws.amazo The following command creates a user pool named `test`: ```bash -awslocal cognito-idp create-user-pool --pool-name test +lstk aws cognito-idp create-user-pool --pool-name test ``` ```bash title="Output" @@ -72,7 +72,7 @@ pool_id= Alternatively, you can use JSON processor like [`jq`](https://stedolan.github.io/jq/) to extract the essential information right from the outset when creating a pool. ```bash -pool_id=$(awslocal cognito-idp create-user-pool --pool-name test | jq -rc ".UserPool.Id") +pool_id=$(lstk aws cognito-idp create-user-pool --pool-name test | jq -rc ".UserPool.Id") ``` ### Adding a Client @@ -83,7 +83,7 @@ You can use the [`CreateUserPoolClient`](https://docs.aws.amazon.com/cognito-use Run the following command: ```bash -client_id=$(awslocal cognito-idp create-user-pool-client --user-pool-id $pool_id --client-name test-client | jq -rc ".UserPoolClient.ClientId") +client_id=$(lstk aws cognito-idp create-user-pool-client --user-pool-id $pool_id --client-name test-client | jq -rc ".UserPoolClient.ClientId") ``` ### Using Predefined IDs for Pool Creation @@ -95,7 +95,7 @@ Please note that a valid custom id must be in the format `_`. ```bash -awslocal cognito-idp create-user-pool-client --user-pool-id us-east-1_myid123 --client-name _custom_id_:myclient123 +lstk aws cognito-idp create-user-pool-client --user-pool-id us-east-1_myid123 --client-name _custom_id_:myclient123 ``` ```bash title="Output" @@ -127,7 +127,7 @@ You can now use the [`SignUp`](https://docs.aws.amazon.com/cognito-user-identity Run the following command: ```bash -awslocal cognito-idp sign-up \ +lstk aws cognito-idp sign-up \ --client-id $client_id \ --username example_user \ --password 12345678Aa! \ @@ -154,7 +154,7 @@ You can confirm the user with the activation code, using the [`ConfirmSignUp`](h Execute the following command: ```bash -awslocal cognito-idp confirm-sign-up \ +lstk aws cognito-idp confirm-sign-up \ --client-id $client_id \ --username example_user \ --confirmation-code @@ -164,7 +164,7 @@ Since the above command does not provide a direct response, we need to verify th Run the following command to use the [`ListUsers`](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListUsers.html) API to list the users in the pool: ```bash -awslocal cognito-idp list-users --user-pool-id $pool_id +lstk aws cognito-idp list-users --user-pool-id $pool_id ``` ```bash title="Output" @@ -218,7 +218,7 @@ First, enable software token MFA at the pool level. Setting `MfaConfiguration` to `OPTIONAL` enforces MFA per-user based on their preferences: ```bash -awslocal cognito-idp set-user-pool-mfa-config \ +lstk aws cognito-idp set-user-pool-mfa-config \ --user-pool-id $pool_id \ --software-token-mfa-configuration Enabled=true \ --mfa-configuration OPTIONAL @@ -228,7 +228,7 @@ Sign in once to obtain an access token, then associate a software token for the This returns a `SecretCode` that you register in your authenticator app: ```bash -awslocal cognito-idp associate-software-token --access-token +lstk aws cognito-idp associate-software-token --access-token ``` ```bash title="Output" @@ -240,11 +240,11 @@ awslocal cognito-idp associate-software-token --access-token Verify the token by submitting a code generated from the secret, then set the software token as the user's preferred MFA factor: ```bash -awslocal cognito-idp verify-software-token \ +lstk aws cognito-idp verify-software-token \ --access-token \ --user-code -awslocal cognito-idp set-user-mfa-preference \ +lstk aws cognito-idp set-user-mfa-preference \ --access-token \ --software-token-mfa-settings Enabled=true,PreferredMfa=true ``` @@ -252,7 +252,7 @@ awslocal cognito-idp set-user-mfa-preference \ On the next sign-in, the authentication flow now returns a `SOFTWARE_TOKEN_MFA` challenge instead of issuing tokens directly: ```bash -awslocal cognito-idp initiate-auth \ +lstk aws cognito-idp initiate-auth \ --client-id $client_id \ --auth-flow USER_PASSWORD_AUTH \ --auth-parameters USERNAME=example_user,PASSWORD=12345678Aa! @@ -271,7 +271,7 @@ awslocal cognito-idp initiate-auth \ Respond to the challenge with a fresh TOTP code to complete authentication: ```bash -awslocal cognito-idp respond-to-auth-challenge \ +lstk aws cognito-idp respond-to-auth-challenge \ --client-id $client_id \ --challenge-name SOFTWARE_TOKEN_MFA \ --session \ @@ -286,7 +286,7 @@ Enable email MFA at the pool level by providing an `EmailMfaConfiguration`. The configuration is persisted and returned by [`GetUserPoolMfaConfig`](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUserPoolMfaConfig.html): ```bash -awslocal cognito-idp set-user-pool-mfa-config \ +lstk aws cognito-idp set-user-pool-mfa-config \ --user-pool-id $pool_id \ --email-mfa-configuration 'Message="Your code is {####}",Subject="Your verification code"' \ --mfa-configuration OPTIONAL @@ -296,7 +296,7 @@ Set email as the user's preferred MFA factor. The user must have a verified `email` attribute: ```bash -awslocal cognito-idp admin-set-user-mfa-preference \ +lstk aws cognito-idp admin-set-user-mfa-preference \ --user-pool-id $pool_id \ --username example_user \ --email-mfa-settings Enabled=true,PreferredMfa=true @@ -305,7 +305,7 @@ awslocal cognito-idp admin-set-user-mfa-preference \ `AdminGetUser` now surfaces `EMAIL_OTP` in the user's MFA settings: ```bash -awslocal cognito-idp admin-get-user --user-pool-id $pool_id --username example_user +lstk aws cognito-idp admin-get-user --user-pool-id $pool_id --username example_user ``` ```bash title="Output" @@ -340,7 +340,7 @@ INFO --- [et.reactor-0] l.p.c.s.c.auth_flows : Code verification sent via Respond to the challenge with the emailed code to complete authentication: ```bash -awslocal cognito-idp respond-to-auth-challenge \ +lstk aws cognito-idp respond-to-auth-challenge \ --client-id $client_id \ --challenge-name EMAIL_OTP \ --session \ @@ -455,7 +455,7 @@ Enter the following commands to create the Lambda function: ```bash zip function.zip index.js -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name migrate_users \ --runtime nodejs18.x \ --zip-file fileb://function.zip \ @@ -466,7 +466,7 @@ awslocal lambda create-function \ Subsequently, you can define the corresponding `--lambda-config` when creating the user pool to link it with the Lambda function: ```bash -awslocal cognito-idp create-user-pool \ +lstk aws cognito-idp create-user-pool \ --pool-name test2 \ --lambda-config '{"UserMigration":"arn:aws:lambda:us-east-1:000000000000:function:migrate_users"}' ``` @@ -526,13 +526,13 @@ To get started, follow the example below: ```bash #Create client user pool with a client. -export client_id=$(awslocal cognito-idp create-user-pool-client --user-pool-id $pool_id --client-name test-client --generate-secret | jq -rc ".UserPoolClient.ClientId") +export client_id=$(lstk aws cognito-idp create-user-pool-client --user-pool-id $pool_id --client-name test-client --generate-secret | jq -rc ".UserPoolClient.ClientId") #Retrieve secret. -export client_secret=$(awslocal cognito-idp describe-user-pool-client --user-pool-id $pool_id --client-id $client_id | jq -r '.UserPoolClient.ClientSecret') +export client_secret=$(lstk aws cognito-idp describe-user-pool-client --user-pool-id $pool_id --client-id $client_id | jq -r '.UserPoolClient.ClientSecret') #Create resource server -awslocal cognito-idp create-resource-server \ +lstk aws cognito-idp create-resource-server \ --user-pool-id $pool_id \ --identifier "api-client-organizations" \ --name "Resource Server Name" \ diff --git a/src/content/docs/aws/services/config.mdx b/src/content/docs/aws/services/config.mdx index a0a9f45d9..e85acde07 100644 --- a/src/content/docs/aws/services/config.mdx +++ b/src/content/docs/aws/services/config.mdx @@ -18,7 +18,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Config and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Config and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to specify the resource types you want Config to record and grant it the needful permissions to access an S3 bucket and SNS topic with the AWS CLI. @@ -30,8 +30,8 @@ The SNS topic will be used to notify you when a configuration snapshot is availa You can create a new S3 bucket and SNS topic using the AWS CLI: ```bash -awslocal s3 mb s3://config-test -awslocal sns create-topic --name config-test-topic +lstk aws s3 mb s3://config-test +lstk aws sns create-topic --name config-test-topic ``` ### Create a new configuration recorder @@ -40,7 +40,7 @@ You can now create a new configuration recorder to record configuration changes Run the following command to create a new configuration recorder: ```bash -awslocal configservice put-configuration-recorder \ +lstk aws configservice put-configuration-recorder \ --configuration-recorder name=default,roleARN=arn:aws:iam::000000000000:role/config-role ``` @@ -54,7 +54,7 @@ You can now create a delivery channel object to deliver configuration informatio You have already created the S3 bucket and SNS topic, so you can now create the delivery channel object using the [`PutDeliveryChannel`](https://docs.aws.amazon.com/config/latest/APIReference/API_PutDeliveryChannel.html) API. We're going to create a delivery channel with the following configuration. -You can inline the JSON into the `awslocal` command. +You can inline the JSON into the `lstk aws` command. ```json { @@ -70,7 +70,7 @@ You can inline the JSON into the `awslocal` command. Run the following command to create the delivery channel: ```bash -awslocal configservice put-delivery-channel \ +lstk aws configservice put-delivery-channel \ --delivery-channel '{ "name": "default", "s3BucketName": "config-test", @@ -88,15 +88,15 @@ You can use the [`StartConfigurationRecorder`](https://docs.aws.amazon.com/confi Run the following command to start the configuration recorder: ```bash -awslocal configservice start-configuration-recorder \ +lstk aws configservice start-configuration-recorder \ --configuration-recorder-name default ``` You can list the delivery channels and configuration recorders using the [`DescribeDeliveryChannels`](https://docs.aws.amazon.com/config/latest/APIReference/API_DescribeDeliveryChannels.html) and [`DescribeConfigurationRecorderStatus`](https://docs.aws.amazon.com/config/latest/APIReference/API_DescribeConfigurationRecorderStatus.html) APIs respectively. ```bash -awslocal configservice describe-delivery-channels -awslocal configservice describe-configuration-recorder-status +lstk aws configservice describe-delivery-channels +lstk aws configservice describe-configuration-recorder-status ``` ## Current Limitations diff --git a/src/content/docs/aws/services/docdb.mdx b/src/content/docs/aws/services/docdb.mdx index 70836955d..abe34f6d0 100644 --- a/src/content/docs/aws/services/docdb.mdx +++ b/src/content/docs/aws/services/docdb.mdx @@ -19,7 +19,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w To create a new DocumentDB cluster we use the `create-db-cluster` command as follows: ```bash -awslocal docdb create-db-cluster \ +lstk aws docdb create-db-cluster \ --db-cluster-identifier test-docdb-cluster \ --engine docdb ``` @@ -67,7 +67,7 @@ As we did not specify a `MasterUsername` or `MasterUserPassword` for the creatio To create a new database, we can use the `create-db-instance` command, like in this example: ```bash -awslocal docdb create-db-instance \ +lstk aws docdb create-db-instance \ --db-instance-identifier test-company \ --db-instance-class db.r5.large \ --engine docdb \ @@ -122,7 +122,7 @@ Some noticeable fields: To obtain detailed information about the cluster, we use the `describe-db-cluster` command: ```bash -awslocal docdb describe-db-clusters \ +lstk aws docdb describe-db-clusters \ --db-cluster-identifier test-docdb-cluster ``` @@ -227,7 +227,7 @@ We included a snippet at the very end. We assume you have a `MasterUsername` and `MasterUserPassword` set for DocDB e.g: ```bash -awslocal docdb create-db-cluster \ +lstk aws docdb create-db-cluster \ --db-cluster-identifier test-docdb \ --engine docdb \ --master-user-password S3cretPwd! \ @@ -306,10 +306,10 @@ Make sure you are inside `resources` directory and run: zip -r function.zip . ``` -Finally, we can create the `lambda` function using `awslocal`: +Finally, we can create the `lambda` function using `lstk aws`: ```bash -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name MyNodeLambda \ --runtime nodejs16.x \ --role arn:aws:iam::000000000000:role/lambda-role \ @@ -321,7 +321,7 @@ awslocal lambda create-function \ You can invoke the lambda by calling: ```bash -awslocal lambda invoke \ +lstk aws lambda invoke \ --function-name MyNodeLambda \ outfile ``` diff --git a/src/content/docs/aws/services/dsql.mdx b/src/content/docs/aws/services/dsql.mdx index 2df735c49..f8fe66748 100644 --- a/src/content/docs/aws/services/dsql.mdx +++ b/src/content/docs/aws/services/dsql.mdx @@ -18,7 +18,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Aurora DSQL and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Aurora DSQL and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a cluster, inspect it, and clean it up using the AWS CLI. @@ -29,7 +29,7 @@ You can create a cluster using the [`CreateCluster`](https://docs.aws.amazon.com Run the following command to create a cluster: ```bash -awslocal dsql create-cluster +lstk aws dsql create-cluster ``` ```bash title="Output" @@ -58,7 +58,7 @@ You can retrieve the details of a cluster using the [`GetCluster`](https://docs. Replace the identifier with the one returned in the previous step: ```bash -awslocal dsql get-cluster --identifier 8a71d298-c086-4fb4-a698-d7b4eeb657e6 +lstk aws dsql get-cluster --identifier 8a71d298-c086-4fb4-a698-d7b4eeb657e6 ``` ```bash title="Output" @@ -80,7 +80,7 @@ awslocal dsql get-cluster --identifier 8a71d298-c086-4fb4-a698-d7b4eeb657e6 You can list all clusters in the current account and region using the [`ListClusters`](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_ListClusters.html) API: ```bash -awslocal dsql list-clusters +lstk aws dsql list-clusters ``` ```bash title="Output" @@ -130,7 +130,7 @@ Because clusters are created with deletion protection enabled, you must first di Attempting to delete a protected cluster returns a `ValidationException`. ```bash -awslocal dsql update-cluster \ +lstk aws dsql update-cluster \ --identifier 8a71d298-c086-4fb4-a698-d7b4eeb657e6 \ --no-deletion-protection-enabled ``` @@ -138,7 +138,7 @@ awslocal dsql update-cluster \ You can then delete the cluster using the [`DeleteCluster`](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_DeleteCluster.html) API: ```bash -awslocal dsql delete-cluster --identifier 8a71d298-c086-4fb4-a698-d7b4eeb657e6 +lstk aws dsql delete-cluster --identifier 8a71d298-c086-4fb4-a698-d7b4eeb657e6 ``` ```bash title="Output" @@ -155,13 +155,13 @@ awslocal dsql delete-cluster --identifier 8a71d298-c086-4fb4-a698-d7b4eeb657e6 You can attach tags at creation time with `--tags`, and manage them afterwards using the [`TagResource`](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_TagResource.html), [`UntagResource`](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_UntagResource.html), and [`ListTagsForResource`](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_ListTagsForResource.html) APIs. ```bash -awslocal dsql create-cluster --tags Name=my-cluster,Env=dev +lstk aws dsql create-cluster --tags Name=my-cluster,Env=dev ``` Add or update tags on an existing cluster: ```bash -awslocal dsql tag-resource \ +lstk aws dsql tag-resource \ --resource-arn arn:aws:dsql:us-east-1:000000000000:cluster/8a71d298-c086-4fb4-a698-d7b4eeb657e6 \ --tags Team=platform ``` @@ -169,7 +169,7 @@ awslocal dsql tag-resource \ List the tags on a resource: ```bash -awslocal dsql list-tags-for-resource \ +lstk aws dsql list-tags-for-resource \ --resource-arn arn:aws:dsql:us-east-1:000000000000:cluster/8a71d298-c086-4fb4-a698-d7b4eeb657e6 ``` @@ -186,7 +186,7 @@ awslocal dsql list-tags-for-resource \ Remove tags by key: ```bash -awslocal dsql untag-resource \ +lstk aws dsql untag-resource \ --resource-arn arn:aws:dsql:us-east-1:000000000000:cluster/8a71d298-c086-4fb4-a698-d7b4eeb657e6 \ --tag-keys Env ``` @@ -196,7 +196,7 @@ awslocal dsql untag-resource \ You can attach a resource-based policy to a cluster using the [`PutClusterPolicy`](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_PutClusterPolicy.html) API, then read and remove it with [`GetClusterPolicy`](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_GetClusterPolicy.html) and [`DeleteClusterPolicy`](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_DeleteClusterPolicy.html). ```bash -awslocal dsql put-cluster-policy \ +lstk aws dsql put-cluster-policy \ --identifier 8a71d298-c086-4fb4-a698-d7b4eeb657e6 \ --policy '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"AWS":"arn:aws:iam::000000000000:root"},"Action":"dsql:DbConnect","Resource":"*"}]}' ``` @@ -210,7 +210,7 @@ awslocal dsql put-cluster-policy \ Retrieve the stored policy: ```bash -awslocal dsql get-cluster-policy --identifier 8a71d298-c086-4fb4-a698-d7b4eeb657e6 +lstk aws dsql get-cluster-policy --identifier 8a71d298-c086-4fb4-a698-d7b4eeb657e6 ``` :::note @@ -222,7 +222,7 @@ Cluster policies are stored and returned as-is but are not enforced by LocalStac You can manage stream metadata using the [`CreateStream`](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_CreateStream.html), [`GetStream`](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_GetStream.html), [`ListStreams`](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_ListStreams.html), and [`DeleteStream`](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_DeleteStream.html) APIs. ```bash -awslocal dsql create-stream \ +lstk aws dsql create-stream \ --cluster-identifier 8a71d298-c086-4fb4-a698-d7b4eeb657e6 \ --target-definition '{"kinesis":{"streamArn":"arn:aws:kinesis:us-east-1:000000000000:stream/my-stream","roleArn":"arn:aws:iam::000000000000:role/dsql-stream-role"}}' \ --ordering UNORDERED \ @@ -244,7 +244,7 @@ awslocal dsql create-stream \ List the streams of a cluster: ```bash -awslocal dsql list-streams --cluster-identifier 8a71d298-c086-4fb4-a698-d7b4eeb657e6 +lstk aws dsql list-streams --cluster-identifier 8a71d298-c086-4fb4-a698-d7b4eeb657e6 ``` :::note @@ -256,7 +256,7 @@ Streams are backed as metadata only; no change-data-capture (CDC) records are em You can retrieve the synthesised VPC endpoint service name for a cluster using the [`GetVpcEndpointServiceName`](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_GetVpcEndpointServiceName.html) API: ```bash -awslocal dsql get-vpc-endpoint-service-name --identifier 8a71d298-c086-4fb4-a698-d7b4eeb657e6 +lstk aws dsql get-vpc-endpoint-service-name --identifier 8a71d298-c086-4fb4-a698-d7b4eeb657e6 ``` ```bash title="Output" diff --git a/src/content/docs/aws/services/dynamodb.mdx b/src/content/docs/aws/services/dynamodb.mdx index 69e1b9846..bf171dbda 100644 --- a/src/content/docs/aws/services/dynamodb.mdx +++ b/src/content/docs/aws/services/dynamodb.mdx @@ -18,7 +18,7 @@ DynamoDB emulation is powered by [DynamoDB Local](https://docs.aws.amazon.com/am ## Getting started -This guide is designed for users new to DynamoDB and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to DynamoDB and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create DynamoDB table, along with its replicas, and put an item into the table using the AWS CLI. @@ -29,7 +29,7 @@ You can create a DynamoDB table using the [`CreateTable`](https://docs.aws.amazo Execute the following command to create a table named `global01` with a primary key `id`: ```bash -awslocal dynamodb create-table \ +lstk aws dynamodb create-table \ --table-name global01 \ --key-schema AttributeName=id,KeyType=HASH \ --attribute-definitions AttributeName=id,AttributeType=S \ @@ -70,7 +70,7 @@ You can create replicas of a DynamoDB table using the [`UpdateTable`](https://do Execute the following command to create replicas in `ap-south-1` and `us-west-1` regions: ```bash -awslocal dynamodb update-table \ +lstk aws dynamodb update-table \ --table-name global01 \ --replica-updates '[{"Create": {"RegionName": "eu-central-1"}}, {"Create": {"RegionName": "us-west-1"}}]' \ --region ap-south-1 @@ -105,7 +105,7 @@ You can use the [`ListTables`](https://docs.aws.amazon.com/amazondynamodb/latest Run the following command to list the tables in the `eu-central-1` region: ```bash -awslocal dynamodb list-tables \ +lstk aws dynamodb list-tables \ --region eu-central-1 ``` @@ -123,7 +123,7 @@ You can insert an item into a DynamoDB table using the [`PutItem`](https://docs. Execute the following command to insert an item into the `global01` table: ```bash -awslocal dynamodb put-item \ +lstk aws dynamodb put-item \ --table-name global01 \ --item '{"id":{"S":"foo"}}' \ --region eu-central-1 @@ -133,7 +133,7 @@ You can now query the number of items in the table using the [`DescribeTable`](h Run the following command to query the number of items in the `global01` table from a different region: ```bash -awslocal dynamodb describe-table \ +lstk aws dynamodb describe-table \ --table-name global01 \ --query 'Table.ItemCount' \ --region ap-south-1 diff --git a/src/content/docs/aws/services/dynamodbstreams.mdx b/src/content/docs/aws/services/dynamodbstreams.mdx index c350e9978..a23f91d3f 100644 --- a/src/content/docs/aws/services/dynamodbstreams.mdx +++ b/src/content/docs/aws/services/dynamodbstreams.mdx @@ -18,7 +18,7 @@ The supported APIs are available on our [API coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to DynamoDB Streams and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to DynamoDB Streams and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate the following process using LocalStack: @@ -34,7 +34,7 @@ You can create a DynamoDB table named `BarkTable` using the [`CreateTable`](http Run the following command to create the table: ```bash -awslocal dynamodb create-table \ +lstk aws dynamodb create-table \ --table-name BarkTable \ --attribute-definitions AttributeName=Username,AttributeType=S AttributeName=Timestamp,AttributeType=S \ --key-schema AttributeName=Username,KeyType=HASH AttributeName=Timestamp,KeyType=RANGE \ @@ -84,7 +84,7 @@ Run the following command to create the Lambda function: ```bash zip index.zip index.js -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name publishNewBark \ --zip-file fileb://index.zip \ --role roleARN \ @@ -142,7 +142,7 @@ Create a new file named `payload.json` with the following content: Run the following command to invoke the Lambda function: ```bash -awslocal lambda invoke \ +lstk aws lambda invoke \ --function-name publishNewBark \ --payload file://payload.json \ --cli-binary-format raw-in-base64-out output.txt @@ -161,14 +161,14 @@ You can get the stream ARN using the [`DescribeTable`](https://docs.aws.amazon.c Run the following command to get the stream ARN: ```bash -awslocal dynamodb describe-table --table-name BarkTable +lstk aws dynamodb describe-table --table-name BarkTable ``` You can now create an event source mapping using the [`CreateEventSourceMapping`](https://docs.aws.amazon.com/lambda/latest/dg/API_CreateEventSourceMapping.html) API. Run the following command to create the event source mapping: ```bash -awslocal lambda create-event-source-mapping \ +lstk aws lambda create-event-source-mapping \ --function-name publishNewBark \ --event-source arn:aws:dynamodb:us-east-1:000000000000:table/BarkTable/stream/2024-07-12T06:18:37.101 \ --batch-size 1 \ @@ -193,7 +193,7 @@ You can now test the event source mapping by adding an item to the `BarkTable` t Run the following command to add an item to the table: ```bash -awslocal dynamodb put-item \ +lstk aws dynamodb put-item \ --table-name BarkTable \ --item Username={S="Jane Doe"},Timestamp={S="2016-11-18:14:32:17"},Message={S="Testing...1...2...3"} ``` @@ -206,7 +206,7 @@ You can list the streams using the [`ListStreams`](https://docs.aws.amazon.com/a Run the following command to list the streams: ```bash -awslocal dynamodbstreams list-streams +lstk aws dynamodbstreams list-streams ``` The following output shows the list of streams: @@ -227,7 +227,7 @@ You can also describe the stream using the [`DescribeStream`](https://docs.aws.a Run the following command to describe the stream: ```bash -awslocal dynamodbstreams describe-stream \ +lstk aws dynamodbstreams describe-stream \ --stream-arn arn:aws:dynamodb:us-east-1:000000000000:table/BarkTable/stream/2024-07-12T06:18:37.101 ``` diff --git a/src/content/docs/aws/services/ec2.mdx b/src/content/docs/aws/services/ec2.mdx index 99aba926f..7457d71d7 100644 --- a/src/content/docs/aws/services/ec2.mdx +++ b/src/content/docs/aws/services/ec2.mdx @@ -19,7 +19,7 @@ The list of supported APIs can be found on the [API Coverage section](#api-cover ## Getting started -This guide is designed for users new to EC2 and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to EC2 and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. We will demonstrate how to create an EC2 instance that runs a simple Python web server. LocalStack for AWS running on a Linux host is required as network access to containers is not possible on macOS. @@ -33,7 +33,7 @@ To create a key pair, you can use the [`CreateKeyPair`](https://docs.aws.amazon. Run the following command to create the key pair and pipe the output to a file named `key.pem`: ```bash -awslocal ec2 create-key-pair \ +lstk aws ec2 create-key-pair \ --key-name my-key \ --query 'KeyMaterial' \ --output text | tee key.pem @@ -69,7 +69,7 @@ icacls.exe key.pem /inheritance:r If you already have an SSH public key that you wish to use, such as the one located in your home directory at `~/.ssh/id_rsa.pub`, you can import it instead. ```bash -awslocal ec2 import-key-pair --key-name my-key --public-key-material "$(cat ~/.ssh/id_rsa.pub)" +lstk aws ec2 import-key-pair --key-name my-key --public-key-material "$(cat ~/.ssh/id_rsa.pub)" ``` If you only have the SSH private key, a public key can be generated using the following command, and then imported: @@ -85,7 +85,7 @@ You can add rules to the security group using the [`AuthorizeSecurityGroupIngres Run the following command to add a rule to allow inbound traffic on port 8000: ```bash -awslocal ec2 authorize-security-group-ingress \ +lstk aws ec2 authorize-security-group-ingress \ --group-id default \ --protocol tcp \ --port 8000 \ @@ -100,7 +100,7 @@ You can fetch the Security Group ID using the [`DescribeSecurityGroups`](https:/ Run the following command to fetch the Security Group ID: ```bash -awslocal ec2 describe-security-groups +lstk aws ec2 describe-security-groups ``` ```bash title="Output" @@ -132,7 +132,7 @@ You can now run an EC2 instance using the [`RunInstances`](https://docs.aws.amaz Run the following command to run an EC2 instance by adding the appropriate Security Group ID that we fetched in the previous step: ```bash -awslocal ec2 run-instances \ +lstk aws ec2 run-instances \ --image-id ami-df5de72bdb3b \ --count 1 \ --instance-type t3.nano \ @@ -147,12 +147,12 @@ You can now open the LocalStack logs to find the IP address of the locally emula Run the following command to open the LocalStack logs: ```bash -localstack logs +lstk logs ``` ```bash title="Output" -2023-08-16T17:18:29.702 INFO --- [ asgi_gw_0] l.s.ec2.vmmanager.docker : Instance i-b07acefd77a3c415f will be accessible via SSH at: 127.0.0.1:12862, 172.17.0.4:22 -2023-08-16T17:18:29.702 INFO --- [ asgi_gw_0] l.s.ec2.vmmanager.docker : Instance i-b07acefd77a3c415f port mappings (container -> host): {'8000/tcp': 29043, '22/tcp': 12862} +emulator | 2023-08-16T17:18:29.702 INFO --- [ asgi_gw_0] l.s.ec2.vmmanager.docker : Instance i-b07acefd77a3c415f will be accessible via SSH at: 127.0.0.1:12862, 172.17.0.4:22 +emulator | 2023-08-16T17:18:29.702 INFO --- [ asgi_gw_0] l.s.ec2.vmmanager.docker : Instance i-b07acefd77a3c415f port mappings (container -> host): {'8000/tcp': 29043, '22/tcp': 12862} ``` You can now use the IP address to test the Python Web Server. @@ -186,7 +186,7 @@ This section assumes that you have created or imported an SSH key pair named `my When running the EC2 instance, make sure to pass the `--key-name` parameter to the command: ```bash -awslocal ec2 run-instances --key-name my-key ... +lstk aws ec2 run-instances --key-name my-key ... ``` Once the instance is up and running, we can use the `ssh` command to set up an SSH connection. @@ -260,7 +260,7 @@ All LocalStack-managed Docker AMIs bear the resource tag `ec2_vm_manager:docker` These can be listed using: ```bash -awslocal ec2 describe-images \ +lstk aws ec2 describe-images \ --filters Name=tag:ec2_vm_manager,Values=docker ``` @@ -318,12 +318,12 @@ The system supports up to 32 ingress ports. This constraint is in place to prevent exhausting free ports on the host. ```bash -awslocal ec2 authorize-security-group-ingress \ +lstk aws ec2 authorize-security-group-ingress \ --group-id default \ --protocol tcp \ --port 8080 -awslocal ec2 describe-security-groups --group-names default +lstk aws ec2 describe-security-groups --group-names default ``` The port mapping details are provided in the logs when the instance starts up. @@ -359,7 +359,7 @@ EOF We can then start an EC2 instance, specifying a block device mapping under the device name `/ebs-dev/sda1`, and pointing to our `init.sh` user data script: ```bash -awslocal ec2 run-instances --image-id ami-ff0fea8310f3 --count 1 --instance-type t3.nano \ +lstk aws ec2 run-instances --image-id ami-ff0fea8310f3 --count 1 --instance-type t3.nano \ --block-device-mapping '{"DeviceName":"/ebs-dev/sda1","Ebs":{"VolumeSize":10}}' \ --user-data file://init.sh ``` @@ -570,7 +570,7 @@ Only the images that follow the above naming scheme will be recognised by LocalS These AMIs will also have the resource tag `ec2_vm_manager:libvirt`. ```bash -awslocal ec2 describe-images --filters Name=tag:ec2_vm_manager,Values=libvirt +lstk aws ec2 describe-images --filters Name=tag:ec2_vm_manager,Values=libvirt ``` ### Instances diff --git a/src/content/docs/aws/services/ecr.mdx b/src/content/docs/aws/services/ecr.mdx index 69116e5d2..56bb84891 100644 --- a/src/content/docs/aws/services/ecr.mdx +++ b/src/content/docs/aws/services/ecr.mdx @@ -18,7 +18,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Elastic Container Registry and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Elastic Container Registry and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to build and push a Docker image to a local ECR repository. @@ -77,7 +77,7 @@ You can create an ECR repository using the [`CreateRepository`](https://docs.aws Run the following command to create a repository named `localstack-ecr-repository`: ```bash -awslocal ecr create-repository \ +lstk aws ecr create-repository \ --repository-name localstack-ecr-repository \ --image-scanning-configuration scanOnPush=true ``` @@ -122,7 +122,7 @@ The image will take a few seconds to push to the repository. You can run the following command to verify that the image was pushed successfully: ```bash -awslocal ecr list-images --repository-name localstack-ecr-repository +lstk aws ecr list-images --repository-name localstack-ecr-repository ``` ```bash title="Output" diff --git a/src/content/docs/aws/services/ecs.mdx b/src/content/docs/aws/services/ecs.mdx index 1765d42f3..b31121719 100644 --- a/src/content/docs/aws/services/ecs.mdx +++ b/src/content/docs/aws/services/ecs.mdx @@ -19,7 +19,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting Started -This guide is designed for users new to ECS and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to ECS and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create an ECS service using the AWS CLI @@ -34,7 +34,7 @@ ECS tasks and services run on a cluster. Execute the following command to create an ECS cluster named `mycluster`: ```bash -awslocal ecs create-cluster --cluster-name mycluster +lstk aws ecs create-cluster --cluster-name mycluster ``` ```bash title="Output" @@ -90,7 +90,7 @@ To create a task definition that runs an `ubuntu` container forever (by running and then run the following command: ```bash -awslocal ecs register-task-definition --cli-input-json file://task_definition.json +lstk aws ecs register-task-definition --cli-input-json file://task_definition.json ``` ```bash title="Output" @@ -150,7 +150,7 @@ This will create a number of containers in replica mode meaning they are distrib To create a service, execute the following command: ```bash -awslocal ecs create-service --service-name myservice --cluster mycluster --task-definition myfamily --desired-count 1 +lstk aws ecs create-service --service-name myservice --cluster mycluster --task-definition myfamily --desired-count 1 ``` ```bash title="Output" @@ -214,7 +214,7 @@ CONTAINER ID IMAGE COMMAND CREATED To access the generated logs from the container, run the following command: ```bash -awslocal logs filter-log-events --log-group-name myloggroup --query 'events[].message' +lstk aws logs filter-log-events --log-group-name myloggroup --query 'events[].message' ``` ```bash title="Output" diff --git a/src/content/docs/aws/services/efs.mdx b/src/content/docs/aws/services/efs.mdx index f6d488b5f..336289665 100644 --- a/src/content/docs/aws/services/efs.mdx +++ b/src/content/docs/aws/services/efs.mdx @@ -18,7 +18,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Elastic File System and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Elastic File System and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a file system, apply an IAM resource-based policy, and create a lifecycle configuration using the AWS CLI. @@ -29,7 +29,7 @@ To create a new, empty file system you can use the [`CreateFileSystem`](https:// Run the following command to create a new file system: ```bash -awslocal efs create-file-system \ +lstk aws efs create-file-system \ --performance-mode generalPurpose \ --throughput-mode bursting \ --encrypted \ @@ -59,7 +59,7 @@ You can also describe the locally available file systems using the [`DescribeFil Run the following command to describe the local file systems available: ```bash -awslocal efs describe-file-systems +lstk aws efs describe-file-systems ``` You can alternatively pass the `--file-system-id` parameter to the `describe-file-system` command to retrieve information about a specific file system in AWS CLI. @@ -70,7 +70,7 @@ You can apply an EFS `FileSystemPolicy` to an EFS file system using the [`PutFil Run the following command to apply a policy to the file system created in the previous step: ```bash -awslocal efs put-file-system-policy \ +lstk aws efs put-file-system-policy \ --file-system-id \ --policy "{\"Version\":\"2012-10-17\",\"Id\":\"ExamplePolicy01\",\"Statement\":[{\"Sid\":\"ExampleStatement01\",\"Effect\":\"Allow\",\"Principal\":{\"AWS\":\"*\"},\"Action\":[\"elasticfilesystem:ClientMount\",\"elasticfilesystem:ClientWrite\"],\"Resource\":\"arn:aws:elasticfilesystem:us-east-1:000000000000:file-system/fs-34feac549e66b814\"}]}" ``` @@ -79,7 +79,7 @@ You can list the file system policies using the [`DescribeFileSystemPolicy`](htt Run the following command to list the file system policies: ```bash -awslocal efs describe-file-system-policy \ +lstk aws efs describe-file-system-policy \ --file-system-id ``` @@ -92,7 +92,7 @@ You can create a lifecycle configuration for an EFS file system using the [`PutL Run the following command to create a lifecycle configuration for the file system created in the previous step: ```bash -awslocal efs put-lifecycle-configuration \ +lstk aws efs put-lifecycle-configuration \ --file-system-id \ --lifecycle-policies "{\"TransitionToIA\":\"AFTER_30_DAYS\"}" ``` diff --git a/src/content/docs/aws/services/eks.mdx b/src/content/docs/aws/services/eks.mdx index 38d2a5639..c0bb99d88 100644 --- a/src/content/docs/aws/services/eks.mdx +++ b/src/content/docs/aws/services/eks.mdx @@ -18,7 +18,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Elastic Kubernetes Service and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Elastic Kubernetes Service and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. To interact with the Kubernetes cluster, you should also install [`kubectl`](https://kubernetes.io/docs/tasks/tools/). Start your LocalStack container using your preferred method. @@ -31,7 +31,7 @@ First we need to create a VPC for the EKS cluster. You can create a new VPC usin Run the following command: ```bash title="Create VPC" -awslocal ec2 create-vpc --cidr-block 10.0.0.0/16 +lstk aws ec2 create-vpc --cidr-block 10.0.0.0/16 ``` ```bash title="Output" @@ -50,7 +50,7 @@ Next, we need to create a subnet in the VPC. You can create a 2 subnets using th Run the following command: ```bash title="Create Subnet 1" -awslocal ec2 create-subnet \ +lstk aws ec2 create-subnet \ --vpc-id \ --cidr-block 10.0.1.0/24 \ --availability-zone us-east-1a @@ -69,7 +69,7 @@ awslocal ec2 create-subnet \ ``` ```bash title="Create Subnet 2" -awslocal ec2 create-subnet \ +lstk aws ec2 create-subnet \ --vpc-id \ --cidr-block 10.0.2.0/24 \ --availability-zone us-east-1b @@ -107,7 +107,7 @@ You can create a new cluster using the [`CreateCluster` API](https://docs.aws.am Run the following command: ```bash title="Create Cluster" -awslocal eks create-cluster \ +lstk aws eks create-cluster \ --name cluster1 \ --role-arn "arn:aws:iam::000000000000:role/eks-role" \ --resources-vpc-config '{"subnetIds":["", ""]}' @@ -142,7 +142,7 @@ The cluster creation process may take a few moments as LocalStack sets up the ne Run the following command to wait for the cluster status to become `ACTIVE`: ```bash title="Wait for Cluster" -awslocal eks wait cluster-active --name cluster1 +lstk aws eks wait cluster-active --name cluster1 ``` :::note @@ -173,7 +173,7 @@ You can create a managed node group for your EKS cluster using the [`CreateNodeg Run the following command: ```bash title="Create Node Group" -awslocal eks create-nodegroup \ +lstk aws eks create-nodegroup \ --cluster-name cluster1 \ --nodegroup-name nodegroup1 \ --node-role arn:aws:iam::000000000000:role/eks-nodegroup-role \ @@ -216,7 +216,7 @@ The node group creation process may take a few moments as LocalStack sets up the You can wait for the node group status to become `ACTIVE` by running the following command: ```bash title="Wait for Node Group" -awslocal eks wait nodegroup-active --cluster-name cluster1 --nodegroup-name nodegroup1 +lstk aws eks wait nodegroup-active --cluster-name cluster1 --nodegroup-name nodegroup1 ``` At this point, your EKS cluster is fully operational and ready to deploy workloads. @@ -250,7 +250,7 @@ You can create a new ECR repository using the [`CreateRepository` API](https://d Run the following command: ```bash -awslocal ecr create-repository --repository-name "fancier-nginx" +lstk aws ecr create-repository --repository-name "fancier-nginx" ``` ```bash title="Output" @@ -296,7 +296,7 @@ Next, we can configure `kubectl` to use the EKS cluster, using the [`UpdateKubec Run the following command: ```bash -awslocal eks update-kubeconfig --name cluster1 && \ +lstk aws eks update-kubeconfig --name cluster1 && \ kubectl config use-context arn:aws:eks:us-east-1:000000000000:cluster/cluster1 ``` @@ -476,7 +476,7 @@ LocalStack resolves the standard EKS AMI [SSM public parameters](https://docs.aw ```bash title="Resolve AL2023 AMI" -awslocal ssm get-parameter \ +lstk aws ssm get-parameter \ --name /aws/service/eks/optimized-ami/1.35/amazon-linux-2023/x86_64/standard/recommended/image_id \ --query 'Parameter.Value' --output text ``` @@ -487,7 +487,7 @@ ami-eks-k3d-1.35-amd64-standard ```bash title="Resolve Bottlerocket AMI" -awslocal ssm get-parameter \ +lstk aws ssm get-parameter \ --name /aws/service/bottlerocket/aws-k8s-1.35/x86_64/latest/image_id \ --query 'Parameter.Value' --output text ``` @@ -535,7 +535,7 @@ The walkthrough below assumes a cluster named `cluster1` that is already `ACTIVE 2. Launch an EC2 instance using the resolved AL2023 AMI and the user-data file: ```bash title="Launch AL2023 node" - awslocal ec2 run-instances \ + lstk aws ec2 run-instances \ --image-id ami-eks-k3d-1.35-amd64-standard \ --count 1 \ --instance-type t3.medium \ @@ -565,7 +565,7 @@ The walkthrough below assumes a cluster named `cluster1` that is already `ACTIVE 2. Launch an EC2 instance using the resolved Bottlerocket AMI: ```bash title="Launch Bottlerocket node" - awslocal ec2 run-instances \ + lstk aws ec2 run-instances \ --image-id ami-eks-k3d-1.35-amd64 \ --count 1 \ --instance-type m5.large \ @@ -580,7 +580,7 @@ The walkthrough below assumes a cluster named `cluster1` that is already `ACTIVE Point `kubectl` at the cluster and list the nodes: ```bash -awslocal eks update-kubeconfig --name cluster1 && \ +lstk aws eks update-kubeconfig --name cluster1 && \ kubectl config use-context arn:aws:eks:us-east-1:000000000000:cluster/cluster1 ``` @@ -648,10 +648,22 @@ volumes: - "${HOME}/.kube/config:/root/.kube/config" ``` -When using the LocalStack CLI, please configure the `DOCKER_FLAGS` to mount the kubeconfig into the container: +When using `lstk`, add the mount and provider variable to your `config.toml`: + +```toml +[[containers]] +type = "aws" +volumes = ["~/.kube/config:/root/.kube/config"] +env = ["k8s-provider"] + +[env.k8s-provider] +MANAGED_K8S_PROVIDER = "local" +``` + +Then start LocalStack: ```bash -DOCKER_FLAGS="-v ${HOME}/.kube/config:/root/.kube/config" localstack start +lstk start ``` :::note @@ -667,7 +679,7 @@ By default, the Kubernetes API is assumed to run on the local TCP port `6443`. You can create an EKS Cluster configuration using the following command: ```bash -awslocal eks create-cluster --name cluster1 --role-arn arn:aws:iam::000000000000:role/eks-role --resources-vpc-config '{}' +lstk aws eks create-cluster --name cluster1 --role-arn arn:aws:iam::000000000000:role/eks-role --resources-vpc-config '{}' ``` ```bash title="Output" @@ -686,7 +698,7 @@ awslocal eks create-cluster --name cluster1 --role-arn arn:aws:iam::000000000000 And check that it was created with: ```bash -awslocal eks list-clusters +lstk aws eks list-clusters ``` ```bash title="Output" @@ -713,7 +725,7 @@ If you need to customize the port or expose the load balancer on multiple ports, For instance, if you want to expose the load balancer on ports 8085 and 8086, you can use the following tag definition when creating the cluster: ```bash -awslocal eks create-cluster \ +lstk aws eks create-cluster \ --name cluster1 \ --role-arn arn:aws:iam::000000000000:role/eks-role \ --resources-vpc-config '{}' --tags '{"_lb_ports_":"8085,8086"}' @@ -804,7 +816,7 @@ If you have specific directories that you want to mount from your local developm When creating your cluster, include the special tag `_volume_mount_`, which allows you to define the desired volume mounting configuration from your local development machine to the cluster nodes. ```bash -awslocal eks create-cluster \ +lstk aws eks create-cluster \ --name cluster1 \ --role-arn arn:aws:iam::000000000000:role/eks-role \ --resources-vpc-config '{}' \ @@ -882,8 +894,18 @@ Users can specify the desired version when creating an EKS cluster in LocalStack When LocalStack creates a k3d-backed EKS cluster, it starts the k3s server with an explicit cluster token. This token is used to authenticate agent nodes joining the cluster, enabling dynamic node registration. By default, LocalStack uses `localstack-k3d-cluster-token` as the cluster token. You can override this value using the `EKS_K3D_CLUSTER_TOKEN` configuration variable: +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +env = ["k3d-token"] + +[env.k3d-token] +EKS_K3D_CLUSTER_TOKEN = "my-custom-token" +``` + ```bash -EKS_K3D_CLUSTER_TOKEN=my-custom-token localstack start +lstk start ``` Any agent nodes added to the cluster — whether via k3d node create or k3s agent — will use the same token to authenticate with the k3s server. diff --git a/src/content/docs/aws/services/elasticache.mdx b/src/content/docs/aws/services/elasticache.mdx index 5ae1ed007..59aa10eb4 100644 --- a/src/content/docs/aws/services/elasticache.mdx +++ b/src/content/docs/aws/services/elasticache.mdx @@ -22,14 +22,14 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to ElastiCache and assumes basic knowledge of the AWS CLI and our `awslocal` wrapper script. +This guide is designed for users new to ElastiCache and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. ### Single cache cluster After starting LocalStack for AWS, you can create a cluster with the following command. ```bash -awslocal elasticache create-cache-cluster \ +lstk aws elasticache create-cache-cluster \ --cache-cluster-id my-redis-cluster \ --cache-node-type cache.t2.micro \ --engine redis \ @@ -39,7 +39,7 @@ awslocal elasticache create-cache-cluster \ Wait for it to be available, then you can use the cluster endpoint for Redis operations. ```bash -awslocal elasticache describe-cache-clusters --show-cache-node-info --query "CacheClusters[0].CacheNodes[0].Endpoint" +lstk aws elasticache describe-cache-clusters --show-cache-node-info --query "CacheClusters[0].CacheNodes[0].Endpoint" ``` ```bash title="Output" @@ -64,7 +64,7 @@ redis-cli -p 4510 get foo ### Replication groups in non-cluster mode ```bash -awslocal elasticache create-replication-group \ +lstk aws elasticache create-replication-group \ --replication-group-id my-redis-replication-group \ --replication-group-description 'my replication group' \ --engine redis \ @@ -76,13 +76,13 @@ Wait for it to be available. When running the following command, you should see one node group when running: ```bash -awslocal elasticache describe-replication-groups --replication-group-id my-redis-replication-group +lstk aws elasticache describe-replication-groups --replication-group-id my-redis-replication-group ``` To retrieve the primary endpoint: ```bash -awslocal elasticache describe-replication-groups --replication-group-id my-redis-replication-group \ +lstk aws elasticache describe-replication-groups --replication-group-id my-redis-replication-group \ --query "ReplicationGroups[0].NodeGroups[0].PrimaryEndpoint" ``` @@ -91,7 +91,7 @@ awslocal elasticache describe-replication-groups --replication-group-id my-redis The cluster mode is enabled by using `--num-node-groups` and `--replicas-per-node-group`: ```bash -awslocal elasticache create-replication-group \ +lstk aws elasticache create-replication-group \ --engine redis \ --replication-group-id my-clustered-redis-replication-group \ --replication-group-description 'my clustered replication group' \ @@ -104,7 +104,7 @@ Note that the group nodes do not have a primary endpoint. Instead they have a `ConfigurationEndpoint`, which you can connect to using `redis-cli -c` where `-c` is for cluster mode. ```bash -awslocal elasticache describe-replication-groups --replication-group-id my-clustered-redis-replication-group \ +lstk aws elasticache describe-replication-groups --replication-group-id my-clustered-redis-replication-group \ --query "ReplicationGroups[0].ConfigurationEndpoint" ``` @@ -126,7 +126,7 @@ To enable full Valkey emulation: 2. Create a cluster with the Valkey engine by including the `--engine valkey` flag in your API call: ```bash - awslocal elasticache create-replication-group \ + lstk aws elasticache create-replication-group \ --replication-group-id my-valkey-group \ --replication-group-description "Valkey test group" \ --engine valkey \ diff --git a/src/content/docs/aws/services/elasticbeanstalk.mdx b/src/content/docs/aws/services/elasticbeanstalk.mdx index 63ef98218..56b6bc230 100644 --- a/src/content/docs/aws/services/elasticbeanstalk.mdx +++ b/src/content/docs/aws/services/elasticbeanstalk.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Elastic Beanstalk and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Elastic Beanstalk and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create an Elastic Beanstalk application and environment with the AWS CLI. @@ -28,7 +28,7 @@ To create an Elastic Beanstalk application, you can use the [`CreateApplication` Run the following command to create an application named `my-app`: ```bash -awslocal elasticbeanstalk create-application \ +lstk aws elasticbeanstalk create-application \ --application-name my-app ``` @@ -46,7 +46,7 @@ You can also use the [`DescribeApplications`](https://docs.aws.amazon.com/elasti Run the following command to retrieve information about the `my-app` application, we created earlier: ```bash -awslocal elasticbeanstalk describe-applications \ +lstk aws elasticbeanstalk describe-applications \ --application-names my-app ``` @@ -56,7 +56,7 @@ To create an Elastic Beanstalk environment, you can use the [`CreateEnvironment` Run the following command to create an environment named `my-environment`: ```bash -awslocal elasticbeanstalk create-environment \ +lstk aws elasticbeanstalk create-environment \ --application-name my-app \ --environment-name my-environment ``` @@ -75,7 +75,7 @@ You can also use the [`DescribeEnvironments`](https://docs.aws.amazon.com/elasti Run the following command to retrieve information about the `my-environment` environment, we created earlier: ```bash -awslocal elasticbeanstalk describe-environments \ +lstk aws elasticbeanstalk describe-environments \ --environment-names my-environment ``` @@ -85,7 +85,7 @@ To create an Elastic Beanstalk application version, you can use the [`CreateAppl Run the following command to create an application version named `v1`: ```bash -awslocal elasticbeanstalk create-application-version \ +lstk aws elasticbeanstalk create-application-version \ --application-name my-app \ --version-label v1 ``` @@ -105,7 +105,7 @@ You can also use the [`DescribeApplicationVersions`](https://docs.aws.amazon.com Run the following command to retrieve information about the `v1` application version, we created earlier: ```bash -awslocal elasticbeanstalk describe-application-versions \ +lstk aws elasticbeanstalk describe-application-versions \ --application-name my-app ``` diff --git a/src/content/docs/aws/services/elb.mdx b/src/content/docs/aws/services/elb.mdx index a08af2d2d..299199a76 100644 --- a/src/content/docs/aws/services/elb.mdx +++ b/src/content/docs/aws/services/elb.mdx @@ -17,7 +17,7 @@ The supported APIs are available on the API coverage section for [ELBv1](#api-co ## Getting started -This guide is designed for users new to Elastic Load Balancing and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Elastic Load Balancing and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create an Application Load Balancer, along with its target group, listener, and rule, and forward requests to an IP target. @@ -36,7 +36,7 @@ To specify the subnet and VPC in which the load balancer will be created, you ca In this example, we will use the subnet and VPC in the `us-east-1f` availability zone. ```bash -subnet_info=$(awslocal ec2 describe-subnets --filters Name=availability-zone,Values=us-east-1f \ +subnet_info=$(lstk aws ec2 describe-subnets --filters Name=availability-zone,Values=us-east-1f \ | jq -r '.Subnets[] | select(.AvailabilityZone == "us-east-1f") | {SubnetId: .SubnetId, VpcId: .VpcId}') subnet_id=$(echo $subnet_info | jq -r '.SubnetId') @@ -48,7 +48,7 @@ To create a load balancer, you can use the [`CreateLoadBalancer`](https://docs.a The following command creates an Application Load Balancer named `example-lb`: ```bash -loadBalancer=$(awslocal elbv2 create-load-balancer --name example-lb \ +loadBalancer=$(lstk aws elbv2 create-load-balancer --name example-lb \ --subnets $subnet_id | jq -r '.LoadBalancers[]|.LoadBalancerArn') ``` @@ -58,7 +58,7 @@ To create a target group, you can use the [`CreateTargetGroup`](https://docs.aws The following command creates a target group named `example-target-group`: ```bash -targetGroup=$(awslocal elbv2 create-target-group --name example-target-group \ +targetGroup=$(lstk aws elbv2 create-target-group --name example-target-group \ --protocol HTTP --target-type ip --port 80 --vpc-id $vpc_id \ | jq -r '.TargetGroups[].TargetGroupArn') ``` @@ -69,7 +69,7 @@ To register a target, you can use the [`RegisterTargets`](https://docs.aws.amazo The following command registers the target with the target group created in the previous step: ```bash -awslocal elbv2 register-targets --targets Id=127.0.0.1,Port=5678,AvailabilityZone=all \ +lstk aws elbv2 register-targets --targets Id=127.0.0.1,Port=5678,AvailabilityZone=all \ --target-group-arn $targetGroup ``` @@ -84,7 +84,7 @@ We create a listener for the load balancer using the [`CreateListener`](https:// The following command creates a listener for the load balancer created in the previous step: ```bash -listenerArn=$(awslocal elbv2 create-listener \ +listenerArn=$(lstk aws elbv2 create-listener \ --protocol HTTP \ --port 80 \ --default-actions '{"Type":"forward","TargetGroupArn":"'$targetGroup'","ForwardConfig":{"TargetGroups":[{"TargetGroupArn":"'$targetGroup'","Weight":11}]}}' \ @@ -95,7 +95,7 @@ To create a rule for the listener, you can use the [`CreateRule`](https://docs.a The following command creates a rule for the listener created above: ```bash -listenerRule=$(awslocal elbv2 create-rule \ +listenerRule=$(lstk aws elbv2 create-rule \ --conditions Field=path-pattern,Values=/ \ --priority 1 \ --actions '{"Type":"forward","TargetGroupArn":"'$targetGroup'","ForwardConfig":{"TargetGroups":[{"TargetGroupArn":"'$targetGroup'","Weight":11}]}}' \ diff --git a/src/content/docs/aws/services/emr.mdx b/src/content/docs/aws/services/emr.mdx index cfcf0779c..9f8d66977 100644 --- a/src/content/docs/aws/services/emr.mdx +++ b/src/content/docs/aws/services/emr.mdx @@ -26,14 +26,14 @@ Alternatively, you can use one of our `*-bigdata` Docker image tags which alread ## Getting started -This guide is designed for users new to EMR and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to EMR and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will create a virtual EMR cluster using the AWS CLI. To create an EMR cluster, run the following command: ```bash -awslocal emr create-cluster \ +lstk aws emr create-cluster \ --release-label emr-5.9.0 \ --instance-groups InstanceGroupType=MASTER,InstanceCount=1,InstanceType=m4.large InstanceGroupType=CORE,InstanceCount=1,InstanceType=m4.large ``` diff --git a/src/content/docs/aws/services/es.mdx b/src/content/docs/aws/services/es.mdx index 8054b430a..7349ca430 100644 --- a/src/content/docs/aws/services/es.mdx +++ b/src/content/docs/aws/services/es.mdx @@ -14,14 +14,14 @@ Any cluster created with the Elasticsearch Service will show up in the OpenSearc ## Creating an Elasticsearch cluster -You can go ahead and use [`awslocal`](https://github.com/localstack/awscli-local) to create a new elasticsearch domain via the `aws es create-elasticsearch-domain` command. +You can go ahead and use [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) to create a new elasticsearch domain via the `lstk aws es create-elasticsearch-domain` command. :::note Unless you use the Elasticsearch default version, the first time you create a cluster with a specific version, the Elasticsearch binary is downloaded, which may take a while to download. ::: ```bash -awslocal es create-elasticsearch-domain --domain-name my-domain +lstk aws es create-elasticsearch-domain --domain-name my-domain ``` ```bash title="Output" @@ -74,7 +74,7 @@ In the LocalStack log you will see something like the following, where you can s and after some time, you should see that the `Processing` state of the domain is set to `false`: ```bash -awslocal es describe-elasticsearch-domain --domain-name my-domain | jq ".DomainStatus.Processing" +lstk aws es describe-elasticsearch-domain --domain-name my-domain | jq ".DomainStatus.Processing" ``` ```bash title="Output" @@ -162,7 +162,7 @@ This can be used to overwrite the behavior of the endpoint strategies described You can also choose custom domains, however it is important to add the edge port (`80`/`443` or by default `4566`). ```bash -awslocal es create-elasticsearch-domain --domain-name my-domain \ +lstk aws es create-elasticsearch-domain --domain-name my-domain \ --elasticsearch-version 7.10 \ --domain-endpoint-options '{ "CustomEndpoint": "http://localhost:4566/my-custom-endpoint", "CustomEndpointEnabled": true }' ``` @@ -265,7 +265,7 @@ volumes: 2. Create the Elasticsearch domain: ```bash - awslocal es create-elasticsearch-domain \ + lstk aws es create-elasticsearch-domain \ --domain-name mylogs-2 \ --elasticsearch-version 7.10 \ --elasticsearch-cluster-config '{ "InstanceType": "m3.xlarge.elasticsearch", "InstanceCount": 4, "DedicatedMasterEnabled": true, "ZoneAwarenessEnabled": true, "DedicatedMasterType": "m3.xlarge.elasticsearch", "DedicatedMasterCount": 3}' @@ -305,7 +305,7 @@ volumes: 3. If the `Processing` status is true, it means that the cluster is not yet healthy. You can run `describe-elasticsearch-domain` to receive the status: ```bash - awslocal es describe-elasticsearch-domain --domain-name mylogs-2 + lstk aws es describe-elasticsearch-domain --domain-name mylogs-2 ``` 4. Check the cluster health endpoint and create indices: diff --git a/src/content/docs/aws/services/events.mdx b/src/content/docs/aws/services/events.mdx index b455bbba3..b7b3f07e4 100644 --- a/src/content/docs/aws/services/events.mdx +++ b/src/content/docs/aws/services/events.mdx @@ -26,7 +26,7 @@ Any value for this variable now points to an invalid provider configuration and ## Getting Started -This guide is designed for users new to EventBridge and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to EventBridge and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate creating an EventBridge rule to run a Lambda function when a custom event is published to an event bus. @@ -36,7 +36,7 @@ We will demonstrate creating an EventBridge rule to run a Lambda function when a First, create a custom EventBridge bus using the [`CreateEventBus`](https://docs.aws.amazon.com/cli/latest/reference/events/create-event-bus.html) API: ```bash -awslocal events create-event-bus \ +lstk aws events create-event-bus \ --name my-custom-bus ``` @@ -61,7 +61,7 @@ Run the following command to create a new Lambda function using the [`CreateFunc ```bash zip function.zip index.js -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name events-example \ --runtime nodejs16.x \ --zip-file fileb://function.zip \ @@ -76,7 +76,7 @@ The output will consist of the `FunctionArn`, which you will need to add the Lam Run the following command to create a new EventBridge rule using the [`PutRule`](https://docs.aws.amazon.com/cli/latest/reference/events/put-rule.html) API: ```bash -awslocal events put-rule \ +lstk aws events put-rule \ --name my-custom-rule \ --event-bus-name my-custom-bus \ --event-pattern '{"source":["my-source"],"detail-type":["my-detail-type"]}' \ @@ -92,7 +92,7 @@ This rule will trigger whenever an event matching this pattern is published to t Next, grant the EventBridge service principal (`events.amazonaws.com`) permission to run the rule, using the [`AddPermission`](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) API: ```bash -awslocal lambda add-permission \ +lstk aws lambda add-permission \ --function-name events-example \ --statement-id my-custom-event \ --action 'lambda:InvokeFunction' \ @@ -116,7 +116,7 @@ Create a file named `targets.json` with the following content: Finally, add the Lambda function as a target to the EventBridge rule using the [`PutTargets`](https://docs.aws.amazon.com/cli/latest/reference/events/put-targets.html) API: ```bash -awslocal events put-targets \ +lstk aws events put-targets \ --rule my-custom-rule \ --event-bus-name my-custom-bus \ --targets file://targets.json @@ -127,7 +127,7 @@ awslocal events put-targets \ Now, send an event that matches the rule pattern to trigger the Lambda function using the [`PutEvents`](https://docs.aws.amazon.com/cli/latest/reference/events/put-events.html) API: ```bash -awslocal events put-events \ +lstk aws events put-events \ --entries '[{"Source": "my-source", "DetailType": "my-detail-type", "Detail": "{\"key\": \"value\"}", "EventBusName": "my-custom-bus"}]' ``` @@ -140,24 +140,24 @@ You can verify the Lambda invocation by checking the CloudWatch logs. Run the following command to list the CloudWatch log groups: ```bash -awslocal logs describe-log-groups +lstk aws logs describe-log-groups ``` The output will contain the log group name, which you can use to list the log streams: ```bash -awslocal logs describe-log-streams \ +lstk aws logs describe-log-streams \ --log-group-name /aws/lambda/events-example ``` Alternatively, you can fetch LocalStack logs to verify the Lambda invocation: ```bash title="Output" -localstack logs +lstk logs ... -2023-07-17T09:37:52.028 INFO --- [ asgi_gw_0] localstack.request.aws : AWS lambda.Invoke => 202 -2023-07-17T09:37:52.106 INFO --- [ asgi_gw_0] localstack.request.http : POST /_localstack_lambda/97e08ac50c18930f131d9dd9744b8df4/invocations/ecb744d0-b3f2-400f-9e49-c85cf12b1e00/logs => 202 -2023-07-17T09:37:52.114 INFO --- [ asgi_gw_0] localstack.request.http : POST /_localstack_lambda/97e08ac50c18930f131d9dd9744b8df4/invocations/ecb744d0-b3f2-400f-9e49-c85cf12b1e00/response => 202 +emulator | 2023-07-17T09:37:52.028 INFO --- [ asgi_gw_0] localstack.request.aws : AWS lambda.Invoke => 202 +emulator | 2023-07-17T09:37:52.106 INFO --- [ asgi_gw_0] localstack.request.http : POST /_localstack_lambda/97e08ac50c18930f131d9dd9744b8df4/invocations/ecb744d0-b3f2-400f-9e49-c85cf12b1e00/logs => 202 +emulator | 2023-07-17T09:37:52.114 INFO --- [ asgi_gw_0] localstack.request.http : POST /_localstack_lambda/97e08ac50c18930f131d9dd9744b8df4/invocations/ecb744d0-b3f2-400f-9e49-c85cf12b1e00/response => 202 ... ``` diff --git a/src/content/docs/aws/services/firehose.mdx b/src/content/docs/aws/services/firehose.mdx index 21f3a57f5..ebc7c40b4 100644 --- a/src/content/docs/aws/services/firehose.mdx +++ b/src/content/docs/aws/services/firehose.mdx @@ -20,7 +20,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Data Firehose and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Data Firehose and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to use Firehose to load Kinesis data into Elasticsearch with S3 Backup with the AWS CLI. @@ -31,7 +31,7 @@ You can create an Elasticsearch domain using the [`create-elasticsearch-domain`] Execute the following command to create a domain named `es-local`: ```bash -awslocal es create-elasticsearch-domain --domain-name es-local +lstk aws es create-elasticsearch-domain --domain-name es-local ``` Save the value of the `Endpoint` field from the response, as it will be required further down to confirm the setup. @@ -44,13 +44,13 @@ Before creating the stream, we need to create an S3 bucket to store our backup d You can do this using the [`mb`](https://docs.aws.amazon.com/cli/latest/reference/s3/mb.html) command: ```bash -awslocal s3 mb s3://kinesis-activity-backup-local +lstk aws s3 mb s3://kinesis-activity-backup-local ``` You can now use the [`CreateStream`](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_CreateStream.html) API to create a Kinesis stream named `kinesis-es-local-stream` with two shards: ```bash -awslocal kinesis create-stream \ +lstk aws kinesis create-stream \ --stream-name kinesis-es-local-stream \ --shard-count 2 ``` @@ -72,7 +72,7 @@ However, when operating within the AWS environment, you need to check the access You can use the [`CreateDeliveryStream`](https://docs.aws.amazon.com/firehose/latest/APIReference/API_CreateDeliveryStream.html) API to create a Firehose delivery stream named `activity-to-elasticsearch-local`: ```bash -awslocal firehose create-delivery-stream \ +lstk aws firehose create-delivery-stream \ --delivery-stream-name activity-to-elasticsearch-local \ --delivery-stream-type KinesisStreamAsSource \ --kinesis-stream-source-configuration "KinesisStreamARN=arn:aws:kinesis:us-east-1:000000000000:stream/kinesis-es-local-stream,RoleARN=arn:aws:iam::000000000000:role/Firehose-Reader-Role" \ @@ -94,7 +94,7 @@ You can use the [`describe-elasticsearch-domain`](https://docs.aws.amazon.com/cl Run the following command: ```bash -awslocal es describe-elasticsearch-domain \ +lstk aws es describe-elasticsearch-domain \ --domain-name es-local | jq ".DomainStatus.Processing" ``` @@ -105,7 +105,7 @@ You can add data to the Kinesis stream using the [`PutRecord`](https://docs.aws. The following command adds a record to the stream: ```bash -awslocal kinesis put-record \ +lstk aws kinesis put-record \ --stream-name kinesis-es-local-stream \ --data '{ "target": "barry" }' \ --partition-key partition @@ -119,7 +119,7 @@ You can use the [`PutRecord`](https://docs.aws.amazon.com/firehose/latest/APIRef The following command adds a record to the stream: ```bash -awslocal firehose put-record \ +lstk aws firehose put-record \ --delivery-stream-name activity-to-elasticsearch-local \ --record '{ "Data": "eyJ0YXJnZXQiOiAiSGVsbG8gd29ybGQifQ==" }' ``` diff --git a/src/content/docs/aws/services/fis.mdx b/src/content/docs/aws/services/fis.mdx index 59626d42a..0b074746f 100644 --- a/src/content/docs/aws/services/fis.mdx +++ b/src/content/docs/aws/services/fis.mdx @@ -43,7 +43,7 @@ Some of these events can automatically be undone after a defined time, such as s ## Getting started -This guide is designed for users new to FIS and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to FIS and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create an experiment that stops EC2 instances. @@ -90,7 +90,7 @@ Nonetheless, they are obligatory fields according to AWS specifications and must Run the following command to create an FIS experiment template using the configuration file we just created: ```bash -awslocal fis create-experiment-template --cli-input-json file://create-experiment.json +lstk aws fis create-experiment-template --cli-input-json file://create-experiment.json ``` The following output would be retrieved: @@ -133,7 +133,7 @@ The following output would be retrieved: You can list all the templates you have created using the [`ListExperimentTemplates`](https://docs.aws.amazon.com/fis/latest/APIReference/API_ListExperimentTemplates.html): ```bash -awslocal fis list-experiment-templates +lstk aws fis list-experiment-templates ``` ### Starting the experiment @@ -141,7 +141,7 @@ awslocal fis list-experiment-templates Now let us start an EC2 instance that will match the criteria we specified in the experiment template. ```bash -awslocal ec2 run-instances \ +lstk aws ec2 run-instances \ --image-id ami-024f768332f0 \ --count 1 \ --tag-specifications '{"ResourceType": "instance", "Tags": [{"Key": "foo", "Value": "bar"}]}' @@ -151,7 +151,7 @@ You can start the experiment using the [`StartExperiment`](https://docs.aws.amaz Run the following command and specify the ID of the experiment template you created earlier: ```bash -awslocal fis start-experiment --experiment-template-id ad16589a-4a91-4aee-88df-c33446605882 +lstk aws fis start-experiment --experiment-template-id ad16589a-4a91-4aee-88df-c33446605882 ``` ```bash title="Output" @@ -196,14 +196,14 @@ You can use the [`ListExperiments`](https://docs.aws.amazon.com/fis/latest/APIRe Run the following command: ```bash -awslocal fis list-experiments +lstk aws fis list-experiments ``` You can fetch the details of your experiment using the [`GetExperiment`](https://docs.aws.amazon.com/fis/latest/APIReference/API_GetExperiment.html) API. Run the following command and specify the ID of the experiment you created earlier: ```bash -awslocal fis get-experiment --id efee7c02-8733-4d7c-9628-1b60bbec9759 +lstk aws fis get-experiment --id efee7c02-8733-4d7c-9628-1b60bbec9759 ``` ### Verifying the outcome @@ -212,7 +212,7 @@ You can now test that the experiment is working as expected by trying to obtain Run the following command: ```bash -awslocal ec2 describe-instance-status \ +lstk aws ec2 describe-instance-status \ --instance-ids i-3c40b52ab72f99c63 \ --output json \ --query InstanceStatuses[0].InstanceState diff --git a/src/content/docs/aws/services/glacier.mdx b/src/content/docs/aws/services/glacier.mdx index aa7f8287f..ef7e615f5 100644 --- a/src/content/docs/aws/services/glacier.mdx +++ b/src/content/docs/aws/services/glacier.mdx @@ -21,7 +21,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Glacier and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Glacier and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a vault, upload an archive, initiate a job to get an inventory details or download an archive, and delete the archive and vault with the AWS CLI. @@ -32,14 +32,14 @@ You can create a vault using the [`CreateVault`](https://docs.aws.amazon.com/ama Run the follow command to create a Glacier Vault named `sample-vault`. ```bash -awslocal glacier create-vault --vault-name sample-vault --account-id - +lstk aws glacier create-vault --vault-name sample-vault --account-id - ``` You can get the details from your vault using the [`DescribeVault`](https://docs.aws.amazon.com/amazonglacier/latest/dev/api-vault-get.html) API. Run the following command to describe your vault. ```bash -awslocal glacier describe-vault --vault-name sample-vault --account-id - +lstk aws glacier describe-vault --vault-name sample-vault --account-id - ``` ```bash title="Output" @@ -60,7 +60,7 @@ Download a random image from the internet and save it as `image.jpg`. Run the following command to upload the file to your Glacier vault: ```bash -awslocal glacier upload-archive --vault-name sample-vault --account-id - --body image.jpg +lstk aws glacier upload-archive --vault-name sample-vault --account-id - --body image.jpg ``` ```bash title="Output" @@ -78,7 +78,7 @@ You can initiate the retrieval of an archive from a vault using the [`InitiateJo To download an archive, you will need to initiate an `archive-retrieval` job first to make the Archive available for download. ```bash -awslocal glacier initiate-job \ +lstk aws glacier initiate-job \ --vault-name sample-vault \ --account-id - \ --job-parameters '{"Type":"archive-retrieval","ArchiveId":"d41d8cd98f00b204e9800998ecf8427e"}' @@ -96,7 +96,7 @@ awslocal glacier initiate-job \ You can list the current and previous processes, called Jobs, to monitor the requests sent to the Glacier API using the [`ListJobs`](https://docs.aws.amazon.com/amazonglacier/latest/dev/api-jobs-get.html) API. ```bash -awslocal glacier list-jobs --vault-name sample-vault --account-id - +lstk aws glacier list-jobs --vault-name sample-vault --account-id - ``` ```bash title="Output" @@ -128,7 +128,7 @@ Once the `ArchiveRetrieval` Job is complete, the data can be downloaded. You can use the `JobId` of the Job to download your archive with the following command: ```bash -awslocal glacier get-job-output \ +lstk aws glacier get-job-output \ --vault-name sample-vault \ --account-id - \ --job-id 25CEOTJ7ZUR5Q7YY0B1O55AE4C3L1502EOHWMNY10IIYEBWEQB73D23S8BVYO9RTRTPLRK2LJLUCCRM52GDV87C9A4JW \ @@ -146,7 +146,7 @@ You can also initiate the retrieval of the inventory of a vault using the same [ Initiate a job of the specified type to get the details of the individual inventory items inside a Vault using the `initiate-job` command: ```bash -awslocal glacier initiate-job \ +lstk aws glacier initiate-job \ --vault-name sample-vault \ --account-id - \ --job-parameters '{"Type":"inventory-retrieval","ArchiveId":"d41d8cd98f00b204e9800998ecf8427e"}' @@ -162,7 +162,7 @@ awslocal glacier initiate-job \ In the same fashion as the archive retrieval, you can now download the result of the inventory retrieval job using `GetJobOutput` using the `JobId` from the result of the previous command: ```bash -awslocal glacier get-job-output \ +lstk aws glacier get-job-output \ --vault-name sample-vault \ --account-id - \ --job-id P5972CSWFR803BHX48OD1A7JWNBFJUMYVWCMZWY55ZJPIJMG1XWFV9ISZPZH1X3LBF0UV3UG6ORETM0EHE5R86Z47B1F \ @@ -194,7 +194,7 @@ You can delete a Glacier archive using the [`DeleteArchive`](https://docs.aws.am Run the following command to delete the previously created archive: ```bash -awslocal glacier delete-archive \ +lstk aws glacier delete-archive \ --vault-name sample-vault \ --account-id - \ --archive-id d41d8cd98f00b204e9800998ecf8427e @@ -207,7 +207,7 @@ You can delete a Glacier vault with the [`DeleteVault`](https://docs.aws.amazon. Run the following command to delete the vault: ```bash -awslocal glacier delete-vault \ +lstk aws glacier delete-vault \ --vault-name sample-vault \ --account-id - ``` diff --git a/src/content/docs/aws/services/glue.mdx b/src/content/docs/aws/services/glue.mdx index cf2ced22c..81c123c5e 100644 --- a/src/content/docs/aws/services/glue.mdx +++ b/src/content/docs/aws/services/glue.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Glue and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Glue and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create databases and table metadata in Glue, run Glue ETL jobs, import databases from Athena, and run Glue Crawlers with the AWS CLI. @@ -32,9 +32,9 @@ These dependencies are automatically fetched when you start up the service, so p The commands below illustrate the creation of some very basic entries (databases, tables) in the Glue data catalog: ```bash -awslocal glue create-database --database-input '{"Name":"db1"}' -awslocal glue create-table --database db1 --table-input '{"Name":"table1"}' -awslocal glue get-tables --database db1 +lstk aws glue create-database --database-input '{"Name":"db1"}' +lstk aws glue create-table --database db1 --table-input '{"Name":"table1"}' +lstk aws glue get-tables --database db1 ``` ```bash title="Output" @@ -73,14 +73,14 @@ if __name__ == '__main__': You can now copy the script to an S3 bucket: ```bash -awslocal s3 mb s3://glue-test -awslocal s3 cp job.py s3://glue-test/job.py +lstk aws s3 mb s3://glue-test +lstk aws s3 cp job.py s3://glue-test/job.py ``` Next, you can create a job definition: ```bash -awslocal glue create-job \ +lstk aws glue create-job \ --name job1 \ --role arn:aws:iam::000000000000:role/glue-role \ --command '{"Name": "pythonshell", "ScriptLocation": "s3://glue-test/job.py"}' @@ -89,13 +89,13 @@ awslocal glue create-job \ You can finally start the job execution: ```bash -awslocal glue start-job-run --job-name job1 +lstk aws glue start-job-run --job-name job1 ``` The returned `JobRunId` can be used to query the status job the job execution, until it becomes `SUCCEEDED`: ```bash -awslocal glue get-job-run --job-name job1 --run-id +lstk aws glue get-job-run --job-name job1 --run-id ``` ```bash title="Output" @@ -125,14 +125,14 @@ CREATE EXTERNAL TABLE db2.table2 (a1 Date, a2 STRING, a3 INT) LOCATION 's3://tes Then this command will import these DB/table definitions into the Glue data catalog: ```bash -awslocal glue import-catalog-to-glue +lstk aws glue import-catalog-to-glue ``` Afterwards, the databases and tables will be available in Glue. You can query the databases with the `get-databases` operation: ```bash -awslocal glue get-databases +lstk aws glue get-databases ``` ```bash title="Output" @@ -154,7 +154,7 @@ awslocal glue get-databases And you can query the databases with the `get-databases` operation: ```bash -awslocal glue get-tables --database-name db2 +lstk aws glue get-tables --database-name db2 ``` ```bash title="Output" @@ -190,30 +190,30 @@ The example below illustrates crawling tables and partition metadata from S3 buc You can first create an S3 bucket with a couple of items: ```bash -awslocal s3 mb s3://test +lstk aws s3 mb s3://test printf "1, 2, 3, 4\n5, 6, 7, 8" > /tmp/file.csv -awslocal s3 cp /tmp/file.csv s3://test/table1/year=2021/month=Jan/day=1/file.csv -awslocal s3 cp /tmp/file.csv s3://test/table1/year=2021/month=Jan/day=2/file.csv -awslocal s3 cp /tmp/file.csv s3://test/table1/year=2021/month=Feb/day=1/file.csv -awslocal s3 cp /tmp/file.csv s3://test/table1/year=2021/month=Feb/day=2/file.csv +lstk aws s3 cp /tmp/file.csv s3://test/table1/year=2021/month=Jan/day=1/file.csv +lstk aws s3 cp /tmp/file.csv s3://test/table1/year=2021/month=Jan/day=2/file.csv +lstk aws s3 cp /tmp/file.csv s3://test/table1/year=2021/month=Feb/day=1/file.csv +lstk aws s3 cp /tmp/file.csv s3://test/table1/year=2021/month=Feb/day=2/file.csv ``` You can then create and trigger the crawler: ```bash -awslocal glue create-database --database-input '{"Name":"db1"}' -awslocal glue create-crawler \ +lstk aws glue create-database --database-input '{"Name":"db1"}' +lstk aws glue create-crawler \ --name c1 \ --database-name db1 \ --role arn:aws:iam::000000000000:role/glue-role \ --targets '{"S3Targets": [{"Path": "s3://test/table1"}]}' -awslocal glue start-crawler --name c1 +lstk aws glue start-crawler --name c1 ``` Finally, you can query the table metadata that has been created by the crawler: ```bash -awslocal glue get-tables --database-name db1 +lstk aws glue get-tables --database-name db1 ``` ```bash title="Output" @@ -228,7 +228,7 @@ awslocal glue get-tables --database-name db1 You can also query the created table partitions: ```bash -awslocal glue get-partitions --database-name db1 --table-name table1 +lstk aws glue get-partitions --database-name db1 --table-name table1 ``` ```bash title="Output" @@ -248,7 +248,7 @@ Below is a rough outline of the steps required to get the integration for the JD You can first create the local Redshift cluster via: ```bash -awslocal redshift create-cluster \ +lstk aws redshift create-cluster \ --cluster-identifier c1 \ --node-type dc1.large \ --master-username test \ @@ -272,21 +272,21 @@ Then you can use any JDBC or Postgres client to create a table `mytable1` in the Next, you're creating the Glue database, the JDBC connection, as well as the crawler: ```bash -awslocal glue create-database --database-input '{"Name":"gluedb1"}' -awslocal glue create-connection --connection-input \ +lstk aws glue create-database --database-input '{"Name":"gluedb1"}' +lstk aws glue create-connection --connection-input \ {"Name":"conn1","ConnectionType":"JDBC","ConnectionProperties":{"USERNAME":"test","PASSWORD":"test","JDBC_CONNECTION_URL":"jdbc:redshift://localhost.localstack.cloud:4510/db1"}}' -awslocal glue create-crawler \ +lstk aws glue create-crawler \ --name c1 \ --database-name gluedb1 \ --role arn:aws:iam::000000000000:role/glue-role \ --targets '{"JdbcTargets":[{"ConnectionName":"conn1","Path":"db1/%/mytable1"}]}' -awslocal glue start-crawler --name c1 +lstk aws glue start-crawler --name c1 ``` Once the crawler has started, you have to wait until the `State` turns to `READY` when querying the current state: ```bash -awslocal glue get-crawler --name c1 +lstk aws glue get-crawler --name c1 ``` Once the crawler has finished running and is back in `READY` state, the Glue table within the `gluedb1` DB should have been populated and can be queried via the API. @@ -305,13 +305,13 @@ Support for other dataformats will be added in the future. You can create a schema registry with the following command: ```bash -awslocal glue create-registry --registry-name demo-registry +lstk aws glue create-registry --registry-name demo-registry ``` You can create a schema in the newly created registry with the `create-schema` command: ```bash -awslocal glue create-schema --schema-name demo-schema \ +lstk aws glue create-schema --schema-name demo-schema \ --registry-id RegistryName=demo-registry \ --data-format AVRO \ --compatibility FORWARD \ @@ -338,7 +338,7 @@ awslocal glue create-schema --schema-name demo-schema \ Once the schema has been created, you can create a new version: ```bash -awslocal glue register-schema-version \ +lstk aws glue register-schema-version \ --schema-id SchemaName=demo-schema,RegistryName=demo-registry \ --schema-definition '{"type":"record","namespace":"Demo","name":"Person","fields":[{"name":"Name","type":"string"}, {"name":"Address","type":"string"}]}' ``` @@ -396,12 +396,12 @@ print("SQL result:", result.toJSON().collect()) You can now run the following commands to create and start the Glue job: ```bash -awslocal s3 mb s3://test -awslocal s3 cp job.py s3://test/job.py -awslocal glue create-job --name job1 --role arn:aws:iam::000000000000:role/test \ +lstk aws s3 mb s3://test +lstk aws s3 cp job.py s3://test/job.py +lstk aws glue create-job --name job1 --role arn:aws:iam::000000000000:role/test \ --glue-version 4.0 \ --command '{"Name": "pythonshell", "ScriptLocation": "s3://test/job.py"}' -awslocal glue start-job-run --job-name job1 +lstk aws glue start-job-run --job-name job1 ``` Retrieve the job run ID from the output of the `start-job-run` command. @@ -417,7 +417,7 @@ In order to see the logs above, make sure to enable `DEBUG=1` in the LocalStack Alternatively, you can also retrieve the job logs programmatically via the CloudWatch Logs API - for example, using the job run ID from the above command. ```bash -awslocal logs get-log-events \ +lstk aws logs get-log-events \ --log-group-name /aws-glue/jobs/logs-v2 \ --log-stream-name ``` diff --git a/src/content/docs/aws/services/iam.mdx b/src/content/docs/aws/services/iam.mdx index 811bd6773..360fdfab3 100644 --- a/src/content/docs/aws/services/iam.mdx +++ b/src/content/docs/aws/services/iam.mdx @@ -19,7 +19,7 @@ The policy coverage is documented in the [IAM coverage documentation](/aws/devel ## Getting started -This guide is designed for users new to IAM and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to IAM and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how you can create a new user named `test`, create an access key pair for the user, and assert that the user is recognized after the access keys are configured in the environment. @@ -28,7 +28,7 @@ By default, in the absence of custom credentials configuration, all requests to Run the following command to use the [`GetCallerIdentity`](https://docs.aws.amazon.com/cli/latest/reference/sts/get-caller-identity.html) API to confirm that the request is running under the root user: ```bash -awslocal sts get-caller-identity +lstk aws sts get-caller-identity ``` ```bash title="Output" @@ -43,14 +43,14 @@ You can now create a new user named `test` using the [`CreateUser`](https://docs Run the following command: ```bash -awslocal iam create-user --user-name test +lstk aws iam create-user --user-name test ``` You can now create an access key pair for the user using the [`CreateAccessKey`](https://docs.aws.amazon.com/cli/latest/reference/iam/create-access-key.html) API. Run the following command: ```bash -awslocal iam create-access-key --user-name test +lstk aws iam create-access-key --user-name test ``` ```bash title="Output" @@ -71,7 +71,7 @@ Run the following command: ```bash export AWS_ACCESS_KEY_ID=LKIAQAAAAAAAGFWKCM5F AWS_SECRET_ACCESS_KEY=DUulXk2N2yD6rgoBBR9A/5iXa6dBcLyDknr925Q5 -awslocal sts get-caller-identity +lstk aws sts get-caller-identity ``` ```bash title="Output" diff --git a/src/content/docs/aws/services/identitystore.mdx b/src/content/docs/aws/services/identitystore.mdx index 7871abf7e..1e4a0cdfd 100644 --- a/src/content/docs/aws/services/identitystore.mdx +++ b/src/content/docs/aws/services/identitystore.mdx @@ -16,7 +16,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is aimed at users who are familiar with the AWS CLI and [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is aimed at users who are familiar with the AWS CLI and [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. It will walk you through the basics of setting up and managing groups within the AWS Identity Store using LocalStack. Start your LocalStack container using your preferred method. @@ -28,7 +28,7 @@ You can create a new group in the Identity Store using the [`CreateGroup`](https Execute the following command to create a group with an identity store ID of `testls`: ```bash -awslocal identitystore create-group --identity-store-id testls +lstk aws identitystore create-group --identity-store-id testls ``` ```bash title="Output" @@ -46,7 +46,7 @@ After creating groups, you might want to list all groups within the Identity Sto Run the following command to list all groups using the [`ListGroups`](https://docs.aws.amazon.com/singlesignon/latest/IdentityStoreAPIReference/API_ListGroups.html) API: ```bash -awslocal identitystore list-groups --identity-store-id testls +lstk aws identitystore list-groups --identity-store-id testls ``` ```bash title="Output" @@ -69,7 +69,7 @@ To view details about a specific group, use the [`DescribeGroup`](https://docs.a Run the following command to describe the group you created in the previous step: ```bash -awslocal describe-group --identity-store-id testls --group-id 38cec731-de22-45bf-9af7-b74457bba884 +lstk aws describe-group --identity-store-id testls --group-id 38cec731-de22-45bf-9af7-b74457bba884 ``` ```bash title="Output" diff --git a/src/content/docs/aws/services/iot-data.mdx b/src/content/docs/aws/services/iot-data.mdx index 81ac669d7..ef73911bc 100644 --- a/src/content/docs/aws/services/iot-data.mdx +++ b/src/content/docs/aws/services/iot-data.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to IoT Data and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to IoT Data and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a thing, update its shadow, get its shadow, and delete its shadow using IoT Data. @@ -28,7 +28,7 @@ You can update the shadow of a thing using the [`UpdateThingShadow`](https://doc Run the following command to update the shadow of a thing named `MyRPi`: ```bash -awslocal iot-data update-thing-shadow \ +lstk aws iot-data update-thing-shadow \ --thing-name "MyRPi" \ --payload "{\"state\":{\"reported\":{\"moisture\":\"okay\"}}}" \ output.txt --cli-binary-format raw-in-base64-out @@ -61,7 +61,7 @@ You can get the shadow of a thing using the [`GetThingShadow`](https://docs.aws. Run the following command to get the shadow: ```bash -awslocal iot-data get-thing-shadow \ +lstk aws iot-data get-thing-shadow \ --thing-name "MyRPi" \ output.txt ``` @@ -74,7 +74,7 @@ You can delete the shadow of a thing using the [`DeleteThingShadow`](https://doc Run the following command to delete the shadow: ```bash -awslocal iot-data delete-thing-shadow \ +lstk aws iot-data delete-thing-shadow \ --thing-name "MyRPi" \ output.txt ``` diff --git a/src/content/docs/aws/services/iot.mdx b/src/content/docs/aws/services/iot.mdx index 635e38191..6ae2b0e6a 100644 --- a/src/content/docs/aws/services/iot.mdx +++ b/src/content/docs/aws/services/iot.mdx @@ -19,14 +19,14 @@ LocalStack ships a [Message Queuing Telemetry Transport (MQTT)](https://mqtt.org ## Getting Started -This guide is for users that are new to IoT and assumes a basic knowledge of the AWS CLI and LocalStack [`awslocal`](https://github.com/localstack/awscli-local) wrapper. +This guide is for users that are new to IoT and assumes a basic knowledge of the AWS CLI and LocalStack [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start LocalStack using your preferred method. To retrieve the MQTT endpoint, use the [`DescribeEndpoint`](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeEndpoint.html) operation. ```bash -awslocal iot describe-endpoint +lstk aws iot describe-endpoint ``` ```bash title="Output" @@ -171,7 +171,7 @@ Currently the `principalIdentifier` and `sessionIdentifier` fields in event payl LocalStack can publish the [registry events](https://docs.aws.amazon.com/iot/latest/developerguide/registry-events.html), if [you enable it](https://docs.aws.amazon.com/iot/latest/developerguide/iot-events.html#iot-events-enable). ```bash -awslocal iot update-event-configurations \ +lstk aws iot update-event-configurations \ --event-configurations '{"THING":{"Enabled": true}}' ``` @@ -221,7 +221,7 @@ const device = new iot.device({ And configure the Lambda environment: ```bash -awslocal lambda update-function-configuration \ +lstk aws lambda update-function-configuration \ --function-name your-function-name \ --environment "Variables={NODE_TLS_REJECT_UNAUTHORIZED=0}" ``` diff --git a/src/content/docs/aws/services/iotwireless.mdx b/src/content/docs/aws/services/iotwireless.mdx index ec6545a65..bf24dbf53 100644 --- a/src/content/docs/aws/services/iotwireless.mdx +++ b/src/content/docs/aws/services/iotwireless.mdx @@ -16,7 +16,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to IoT Wireless and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to IoT Wireless and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to use IoT Wireless to create wireless devices and gateways with the AWS CLI. @@ -27,7 +27,7 @@ You can create a wireless device using the [`CreateWirelessDevice`](https://docs Run the following command to create a wireless device: ```bash -awslocal iotwireless create-device-profile +lstk aws iotwireless create-device-profile ``` The following output would be retrieved: @@ -42,7 +42,7 @@ You can list the device profiles using the [`ListDeviceProfiles`](https://docs.a Run the following command to list the device profiles: ```bash -awslocal iotwireless list-device-profiles +lstk aws iotwireless list-device-profiles ``` The following output would be retrieved: @@ -63,7 +63,7 @@ You can create a wireless device using the [`CreateWirelessDevice`](https://docs Run the following command to create a wireless device: ```bash -awslocal iotwireless create-wireless-device \ +lstk aws iotwireless create-wireless-device \ --cli-input-json file://input.json ``` @@ -92,7 +92,7 @@ You can list the wireless devices using the [`ListWirelessDevices`](https://docs Run the following command to list the wireless devices: ```bash -awslocal iotwireless list-wireless-devices +lstk aws iotwireless list-wireless-devices ``` The following output would be retrieved: @@ -119,7 +119,7 @@ You can create a wireless gateway using the [`CreateWirelessGateway`](https://do Run the following command to create a wireless gateway: ```bash -awslocal iotwireless create-wireless-gateway \ +lstk aws iotwireless create-wireless-gateway \ --lorawan GatewayEui="a1b2c3d4567890ab",RfRegion="US915" \ --name "myFirstLoRaWANGateway" \ --description "Using my first LoRaWAN gateway" @@ -137,7 +137,7 @@ You can list the wireless gateways using the [`ListWirelessGateways`](https://do Run the following command to list the wireless gateways: ```bash -awslocal iotwireless list-wireless-gateways +lstk aws iotwireless list-wireless-gateways ``` The following output would be retrieved: diff --git a/src/content/docs/aws/services/kafka.mdx b/src/content/docs/aws/services/kafka.mdx index 4081df2db..5e154d48e 100644 --- a/src/content/docs/aws/services/kafka.mdx +++ b/src/content/docs/aws/services/kafka.mdx @@ -18,7 +18,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Managed Streaming for Kafka and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Managed Streaming for Kafka and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to configure an MSK Cluster locally, create a Kafka topic, and produce and consume messages. @@ -45,7 +45,7 @@ Create the file and add the following content to it: Run the following command to create the cluster: ```bash -awslocal kafka create-cluster \ +lstk aws kafka create-cluster \ --cluster-name "EventsCluster" \ --broker-node-group-info file://brokernodegroupinfo.json \ --kafka-version "2.8.0" \ @@ -65,7 +65,7 @@ You can describe the cluster using the [`DescribeCluster`](https://docs.aws.amaz Run the following command, replacing `ClusterArn` with the Amazon Resource Name (ARN) you obtained above when you created cluster. ```bash -awslocal kafka describe-cluster \ +lstk aws kafka describe-cluster \ --cluster-arn "arn:aws:kafka:us-east-1:000000000000:cluster/EventsCluster/b154d18a-8ecb-4691-96b2-50348357fc2f-25" ``` @@ -147,7 +147,7 @@ ssl.truststore.location=/tmp/kafka.client.truststore.jks Run the following command, replacing `ClusterArn` with the Amazon Resource Name (ARN) you have. ```bash -awslocal kafka get-bootstrap-brokers \ +lstk aws kafka get-bootstrap-brokers \ --cluster-arn ClusterArn ``` @@ -197,7 +197,7 @@ The configuration for this mapping sets the starting position of the topic to `L Run the following command to use the [`CreateEventSourceMapping`](https://docs.aws.amazon.com/lambda/latest/dg/API_CreateEventSourceMapping.html) API by specifying the Event Source ARN, the topic name, the starting position, and the Lambda function name. ```bash -awslocal lambda create-event-source-mapping \ +lstk aws lambda create-event-source-mapping \ --event-source-arn arn:aws:kafka:us-east-1:000000000000:cluster/EventsCluster \ --topics LocalMSKTopic \ --starting-position LATEST \ @@ -236,13 +236,13 @@ To do so, you must first obtain the ARN of the cluster you want to delete. Run the following command to list all the clusters in the region: ```bash -awslocal kafka list-clusters --region us-east-1 +lstk aws kafka list-clusters --region us-east-1 ``` To initiate the deletion of a cluster, select the corresponding `ClusterARN` from the list of clusters, and then execute the following command: ```bash -awslocal kafka delete-cluster --cluster-arn ClusterArn +lstk aws kafka delete-cluster --cluster-arn ClusterArn ``` ## Resource Browser diff --git a/src/content/docs/aws/services/kinesis.mdx b/src/content/docs/aws/services/kinesis.mdx index 29792d4e1..56843db40 100644 --- a/src/content/docs/aws/services/kinesis.mdx +++ b/src/content/docs/aws/services/kinesis.mdx @@ -19,7 +19,7 @@ Emulation for Kinesis is powered by [Kinesis Mock](https://github.com/etspaceman ## Getting started -This guide is designed for users new to Kinesis Data Streams and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Kinesis Data Streams and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a Lambda function to consume events from a Kinesis stream with the AWS CLI. @@ -45,7 +45,7 @@ Run the following command to create a Lambda function named `ProcessKinesisRecor ```bash zip function.zip index.mjs -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name ProcessKinesisRecords \ --zip-file fileb://function.zip \ --handler index.handler \ @@ -96,7 +96,7 @@ You can use the [`Invoke`](https://docs.aws.amazon.com/lambda/latest/dg/API_Invo Execute the following command: ```bash -awslocal lambda invoke \ +lstk aws lambda invoke \ --function-name ProcessKinesisRecords \ --payload file://input.txt outputfile.txt ``` @@ -107,7 +107,7 @@ You can create a Kinesis Stream using the [`CreateStream`](https://docs.aws.amaz Run the following command to create a Kinesis Stream named `lambda-stream`: ```bash -awslocal kinesis create-stream \ +lstk aws kinesis create-stream \ --stream-name lambda-stream \ --shard-count 1 ``` @@ -116,7 +116,7 @@ You can retrieve the Stream ARN using the [`DescribeStream`](https://docs.aws.am Execute the following command: ```bash -awslocal kinesis describe-stream \ +lstk aws kinesis describe-stream \ --stream-name lambda-stream ``` @@ -147,7 +147,7 @@ You can add an Event Source to your Lambda function using the [`CreateEventSourc Run the following command to add the Kinesis Stream as an Event Source to your Lambda function: ```bash -awslocal lambda create-event-source-mapping \ +lstk aws lambda create-event-source-mapping \ --function-name ProcessKinesisRecords \ --event-source arn:aws:kinesis:us-east-1:000000000000:stream/lambda-stream \ --batch-size 100 \ @@ -160,7 +160,7 @@ You can test the event source mapping by adding a record to the Kinesis Stream u Run the following command to add a record to the Kinesis Stream: ```bash -awslocal kinesis put-record \ +lstk aws kinesis put-record \ --stream-name lambda-stream \ --partition-key 1 \ --data "Hello, this is a test." diff --git a/src/content/docs/aws/services/kinesisanalyticsv2.mdx b/src/content/docs/aws/services/kinesisanalyticsv2.mdx index 094a76fb3..c508e8fba 100644 --- a/src/content/docs/aws/services/kinesisanalyticsv2.mdx +++ b/src/content/docs/aws/services/kinesisanalyticsv2.mdx @@ -29,7 +29,7 @@ LocalStack creates Flink JobManager and TaskManager containers on the Docker net **Running LocalStack inside a Kubernetes cluster with the Docker executor is not supported.** Mounting the host Docker socket (`/var/run/docker.sock`) into a LocalStack pod is not sufficient — the Docker executor cannot create Flink containers in this topology and applications will remain stuck in `STARTING` indefinitely. -If you are running LocalStack outside of Kubernetes (for example, with Docker Compose or the LocalStack CLI), no additional configuration is required and the Docker executor is used automatically. +If you are running LocalStack outside of Kubernetes (for example, with Docker Compose or the `lstk` CLI), no additional configuration is required and the Docker executor is used automatically. ## Getting Started @@ -63,8 +63,8 @@ MSF requires that all application code resides in S3. Create an S3 bucket and upload the compiled Flink application jar. ```bash -awslocal s3api create-bucket --bucket flink-bucket -awslocal s3api put-object --bucket flink-bucket --key job.jar --body ./target/flink-kds-s3.jar +lstk aws s3api create-bucket --bucket flink-bucket +lstk aws s3api put-object --bucket flink-bucket --key job.jar --body ./target/flink-kds-s3.jar ``` ### Output Sink @@ -74,7 +74,7 @@ As mentioned earlier, this Flink application writes the output to an S3 bucket. Create the S3 bucket that will serve as the sink. ```bash -awslocal s3api create-bucket --bucket sink-bucket +lstk aws s3api create-bucket --bucket sink-bucket ``` ### Permissions @@ -99,7 +99,7 @@ Create an IAM role for the running MSF application to assume. ``` ```bash -awslocal iam create-role --role-name msaf-role --assume-role-policy-document file://role.json +lstk aws iam create-role --role-name msaf-role --assume-role-policy-document file://role.json ``` Next create add a permissions policy to this role that permits read and write access to S3. @@ -119,7 +119,7 @@ Next create add a permissions policy to this role that permits read and write ac ``` ```bash -awslocal iam put-role-policy --role-name msaf-role --policy-name msaf-policy --policy-document file://policy.json +lstk aws iam put-role-policy --role-name msaf-role --policy-name msaf-policy --policy-document file://policy.json ``` Now, when the running MSF application assumes this role, it will have the necessary permissions to write to the S3 sink. @@ -129,7 +129,7 @@ Now, when the running MSF application assumes this role, it will have the necess With all prerequisite resources in place, the Flink application can now be created and started. ```bash showshowLineNumbers -awslocal kinesisanalyticsv2 create-application \ +lstk aws kinesisanalyticsv2 create-application \ --application-name msaf-app \ --runtime-environment FLINK-1_20 \ --application-mode STREAMING \ @@ -151,14 +151,14 @@ awslocal kinesisanalyticsv2 create-application \ } }' -awslocal kinesisanalyticsv2 start-application --application-name msaf-app +lstk aws kinesisanalyticsv2 start-application --application-name msaf-app ``` Once the Flink cluster is up and running, the application will stream the results to the sink S3 bucket. You can verify this with: ```bash -awslocal s3api list-objects --bucket sink-bucket +lstk aws s3api list-objects --bucket sink-bucket ``` ## CloudWatch Logging @@ -176,7 +176,7 @@ There are following prerequisites for CloudWatch Logs integration: To add a logging option: ```bash showshowLineNumbers -awslocal kinesisanalyticsv2 add-application-cloud-watch-logging-option \ +lstk aws kinesisanalyticsv2 add-application-cloud-watch-logging-option \ --application-name msaf-app \ --cloud-watch-logging-option '{"LogStreamARN": "arn:aws:logs:us-east-1:000000000000:log-group:msaf-log-group:log-stream:msaf-log-stream"}' ``` @@ -201,7 +201,7 @@ Enabling CloudWatch Logs integration has a significant performance hit. Configured logging options can be retrieved using [DescribeApplication](https://docs.aws.amazon.com/managed-flink/latest/apiv2/API_DescribeApplication.html): ```bash -awslocal kinesisanalyticsv2 describe-application --application-name msaf-app | jq .ApplicationDetail.CloudWatchLoggingOptionDescriptions +lstk aws kinesisanalyticsv2 describe-application --application-name msaf-app | jq .ApplicationDetail.CloudWatchLoggingOptionDescriptions ``` ```bash title="Output" @@ -221,7 +221,7 @@ Log events can be retrieved from CloudWatch Logs using the appropriate operation To retrieve all events: ```bash -awslocal logs get-log-events --log-group-name msaf-log-group --log-stream-name msaf-log-stream +lstk aws logs get-log-events --log-group-name msaf-log-group --log-stream-name msaf-log-stream ``` LocalStack reports both Flink application and Flink framework logs to CloudWatch. @@ -234,11 +234,11 @@ You can manage [resource tags](https://docs.aws.amazon.com/managed-flink/latest/ Tags can also be specified when creating the Flink application using the [CreateApplication](https://docs.aws.amazon.com/managed-flink/latest/apiv2/API_CreateApplication.html) operation. ```bash -awslocal kinesisanalyticsv2 tag-resource \ +lstk aws kinesisanalyticsv2 tag-resource \ --resource-arn arn:aws:kinesisanalytics:us-east-1:000000000000:application/msaf-app \ --tags Key=country,Value=SE -awslocal kinesisanalyticsv2 list-tags-for-resource \ +lstk aws kinesisanalyticsv2 list-tags-for-resource \ --resource-arn arn:aws:kinesisanalytics:us-east-1:000000000000:application/msaf-app ``` @@ -256,7 +256,7 @@ awslocal kinesisanalyticsv2 list-tags-for-resource \ You can also untag the resource: ```bash -awslocal kinesisanalyticsv2 untag-resource \ +lstk aws kinesisanalyticsv2 untag-resource \ --resource-arn arn:aws:kinesisanalytics:us-east-1:000000000000:application/msaf-app \ --tag-keys country ``` diff --git a/src/content/docs/aws/services/kms.mdx b/src/content/docs/aws/services/kms.mdx index 5b3c4d835..36217fc53 100644 --- a/src/content/docs/aws/services/kms.mdx +++ b/src/content/docs/aws/services/kms.mdx @@ -19,7 +19,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to KMS and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to KMS and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a simple symmetric encryption key and use it to encrypt/decrypt data. @@ -30,7 +30,7 @@ To generate a new key within the KMS, you can use the [`CreateKey`](https://docs Execute the following command to create a new key: ```bash -awslocal kms create-key +lstk aws kms create-key ``` By default, this command generates a symmetric encryption key, eliminating the need for any additional arguments. @@ -39,13 +39,13 @@ You can take a look at the `KeyId` of the freshly generated key in the output, a In case the key ID is misplaced, it is possible to retrieve a comprehensive list of IDs and [Amazon Resource Names](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) (ARNs) for all available keys through the following command: ```bash -awslocal kms list-keys +lstk aws kms list-keys ``` Additionally, if needed, you can obtain extensive details about a specific key by providing its key ID or ARN using the subsequent command: ```bash -awslocal kms describe-key --key-id +lstk aws kms describe-key --key-id ``` ### Encrypt the data @@ -56,7 +56,7 @@ To do so, you can use the [`Encrypt`](https://docs.aws.amazon.com/kms/latest/API Execute the following command to encrypt the data: ```bash -awslocal kms encrypt \ +lstk aws kms encrypt \ --key-id 010a4301-4205-4df8-ae52-4c2895d47326 \ --plaintext "some important stuff" \ --output text \ @@ -76,7 +76,7 @@ However, with asymmetric keys the `KEY_ID` has to be specified. Execute the following command to decrypt the data: ```bash -awslocal kms decrypt \ +lstk aws kms decrypt \ --ciphertext-blob fileb://my_encrypted_data \ --output text \ --query Plaintext \ @@ -114,7 +114,7 @@ This can be useful to pre-seed a test environment and use a static `KeyId` for y Below is a simple example to create a key with a custom `KeyId` (note that the `KeyId` should have the format of a UUID): ```bash -awslocal kms create-key --tags '[{"TagKey":"_custom_id_","TagValue":"00000000-0000-0000-0000-000000000001"}]' +lstk aws kms create-key --tags '[{"TagKey":"_custom_id_","TagValue":"00000000-0000-0000-0000-000000000001"}]' ``` The following output will be displayed: @@ -148,7 +148,7 @@ thisisasecurekey You can create a key with custom key material using the following command: ```bash -awslocal kms create-key --tags '[{"TagKey":"_custom_key_material_","TagValue":"dGhpc2lzYXNlY3VyZWtleQ=="}]' +lstk aws kms create-key --tags '[{"TagKey":"_custom_key_material_","TagValue":"dGhpc2lzYXNlY3VyZWtleQ=="}]' ``` The following output will be displayed: diff --git a/src/content/docs/aws/services/lakeformation.mdx b/src/content/docs/aws/services/lakeformation.mdx index d9f6c20d8..732fcf69d 100644 --- a/src/content/docs/aws/services/lakeformation.mdx +++ b/src/content/docs/aws/services/lakeformation.mdx @@ -16,7 +16,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Lake Formation and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Lake Formation and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to register an S3 bucket as a resource in Lake Formation, grant permissions to a user, and list the resources and permissions. @@ -26,7 +26,7 @@ We will demonstrate how to register an S3 bucket as a resource in Lake Formation Create a new S3 bucket named `test-bucket` using the `mb` command: ```bash -awslocal s3 mb s3://test-bucket +lstk aws s3 mb s3://test-bucket ``` You can now register the S3 bucket as a resource in Lake Formation using the [`RegisterResource`](https://docs.aws.amazon.com/lake-formation/latest/dg/API_RegisterResource.html) API. @@ -42,7 +42,7 @@ Create a file named `input.json` with the following content: Run the following command to register the resource: ```bash -awslocal lakeformation register-resource \ +lstk aws lakeformation register-resource \ --cli-input-json file://input.json ``` @@ -52,7 +52,7 @@ You can list the registered resources using the [`ListResources`](https://docs.a Execute the following command to list the resources: ```bash -awslocal lakeformation list-resources +lstk aws lakeformation list-resources ``` ```bash title="Output" @@ -94,7 +94,7 @@ Create a file named `permissions.json` with the following content: Run the following command to grant permissions: ```bash -awslocal lakeformation grant-permissions \ +lstk aws lakeformation grant-permissions \ --cli-input-json file://check.json ``` @@ -104,7 +104,7 @@ You can list the permissions granted to a user or group using the [`ListPermissi Execute the following command to list the permissions: ```bash -awslocal lakeformation list-permissions +lstk aws lakeformation list-permissions ``` ## API Coverage diff --git a/src/content/docs/aws/services/lambda.mdx b/src/content/docs/aws/services/lambda.mdx index df73abc57..15021108b 100644 --- a/src/content/docs/aws/services/lambda.mdx +++ b/src/content/docs/aws/services/lambda.mdx @@ -20,7 +20,7 @@ The supported APIs are available on our [API coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Lambda and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Lambda and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a Lambda function with a Function URL. @@ -46,7 +46,7 @@ Enter the following command to create a new Lambda function: ```bash zip function.zip index.js -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name localstack-lambda-url-example \ --runtime nodejs22.x \ --zip-file fileb://function.zip \ @@ -57,7 +57,7 @@ awslocal lambda create-function \ :::note To create a predictable URL for the function, you can assign a custom ID by specifying the `_custom_id_` tag on the function itself. ```bash -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name localstack-lambda-url-example \ --runtime nodejs22.x \ --zip-file fileb://function.zip \ @@ -83,13 +83,13 @@ Run the following command to invoke the function: ```bash -awslocal lambda invoke --function-name localstack-lambda-url-example \ +lstk aws lambda invoke --function-name localstack-lambda-url-example \ --payload '{"body": "{\"num1\": \"10\", \"num2\": \"10\"}" }' output.txt ``` ```bash -awslocal lambda invoke --function-name localstack-lambda-url-example \ +lstk aws lambda invoke --function-name localstack-lambda-url-example \ --cli-binary-format raw-in-base64-out \ --payload '{"body": "{\"num1\": \"10\", \"num2\": \"10\"}" }' output.txt ``` @@ -106,7 +106,7 @@ With the Function URL property, there is now a new way to call a Lambda Function To create a URL for invoking the function, run the following command: ```bash -awslocal lambda create-function-url-config \ +lstk aws lambda create-function-url-config \ --function-name localstack-lambda-url-example \ --auth-type NONE ``` @@ -118,7 +118,7 @@ The URL will be in the format `http://.lambda-url.us-east-1.localhost. As previously mentioned, when a Lambda Function has a `_custom_id_` tag, LocalStack sets this tag's value as the subdomain in the Function's URL. ```bash -awslocal lambda create-function-url-config \ +lstk aws lambda create-function-url-config \ --function-name localstack-lambda-url-example \ --auth-type NONE ``` @@ -133,7 +133,7 @@ awslocal lambda create-function-url-config \ In addition, if you pass an existing version alias as a `Qualifier` to the request, the created URL will combine the custom ID and the alias in the form `-`. ```bash -awslocal lambda create-function-url-config \ +lstk aws lambda create-function-url-config \ --function-name localstack-lambda-url-example \ --auth-type NONE --qualifier test-alias @@ -446,7 +446,7 @@ mkdir -p /tmp/python/ echo 'def util():' > /tmp/python/testlayer.py echo ' print("Output from Lambda layer util function")' >> /tmp/python/testlayer.py (cd /tmp; zip -r testlayer.zip python) -LAYER_ARN=$(awslocal lambda publish-layer-version --layer-name layer1 --zip-file fileb:///tmp/testlayer.zip | jq -r .LayerVersionArn) +LAYER_ARN=$(lstk aws lambda publish-layer-version --layer-name layer1 --zip-file fileb:///tmp/testlayer.zip | jq -r .LayerVersionArn) ``` Next, define a Lambda function that uses our layer: @@ -456,7 +456,7 @@ echo 'def handler(*args, **kwargs):' > /tmp/testlambda.py echo ' import testlayer; testlayer.util()' >> /tmp/testlambda.py echo ' print("Debug output from Lambda function")' >> /tmp/testlambda.py (cd /tmp; zip testlambda.zip testlambda.py) -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name func1 \ --runtime python3.8 \ --role arn:aws:iam::000000000000:role/lambda-role \ @@ -694,7 +694,7 @@ Refer to our [sample `docker-compose.yml` file](https://github.com/localstack/lo If you receive a `ResourceConflictException` when trying to invoke a function, it is currently in a `Pending` state and cannot be executed yet. ```bash -awslocal lambda get-function --function-name my-function +lstk aws lambda get-function --function-name my-function ``` ```bash title="Output" @@ -706,13 +706,13 @@ The function is currently in the following state: Pending To wait until the function becomes `active`, you can use the following command: ```bash -awslocal lambda wait function-active-v2 --function-name my-function +lstk aws lambda wait function-active-v2 --function-name my-function ``` Alternatively, you can check the function state using the [`GetFunction` API](https://docs.aws.amazon.com/lambda/latest/dg/API_GetFunction.html): ```bash -awslocal lambda get-function --function-name my-function +lstk aws lambda get-function --function-name my-function ``` ```bash title="Output" @@ -731,7 +731,7 @@ awslocal lambda get-function --function-name my-function When the function is active, the output will be similar to the following: ```bash -awslocal lambda get-function --function-name my-function +lstk aws lambda get-function --function-name my-function ``` ```bash title="Output" diff --git a/src/content/docs/aws/services/logs.mdx b/src/content/docs/aws/services/logs.mdx index bbb904e7d..1be3b1c40 100644 --- a/src/content/docs/aws/services/logs.mdx +++ b/src/content/docs/aws/services/logs.mdx @@ -42,16 +42,16 @@ First, we setup the required resources. Therefore, we create a kinesis stream, a log group and log stream. Then we can configure the subscription filter. ```bash -awslocal kinesis create-stream --stream-name "logtest" --shard-count 1 -kinesis_arn=$(awslocal kinesis describe-stream --stream-name "logtest" | jq -r .StreamDescription.StreamARN) +lstk aws kinesis create-stream --stream-name "logtest" --shard-count 1 +kinesis_arn=$(lstk aws kinesis describe-stream --stream-name "logtest" | jq -r .StreamDescription.StreamARN) -awslocal logs create-log-group --log-group-name test +lstk aws logs create-log-group --log-group-name test -awslocal logs create-log-stream \ +lstk aws logs create-log-stream \ --log-group-name test \ --log-stream-name test -awslocal logs put-subscription-filter \ +lstk aws logs put-subscription-filter \ --log-group-name "test" \ --filter-name "kinesis_test" \ --filter-pattern "" \ @@ -63,7 +63,7 @@ Next, we can add a log event, that will be forwarded to Kinesis. ```bash timestamp=$(($(date +'%s * 1000 + %-N / 1000000'))) -awslocal logs put-log-events --log-group-name test --log-stream-name test --log-events "[{\"timestamp\": ${timestamp} , \"message\": \"hello from cloudwatch\"}]" +lstk aws logs put-log-events --log-group-name test --log-stream-name test --log-events "[{\"timestamp\": ${timestamp} , \"message\": \"hello from cloudwatch\"}]" ``` Now we can retrieve the data. @@ -71,8 +71,8 @@ In our example, there will only be one record. The data record is base64 encoded and compressed in gzip format: ```bash -shard_iterator=$(awslocal kinesis get-shard-iterator --stream-name logtest --shard-id shardId-000000000000 --shard-iterator-type TRIM_HORIZON | jq -r .ShardIterator) -record=$(awslocal kinesis get-records --limit 10 --shard-iterator $shard_iterator | jq -r '.Records[0].Data') +shard_iterator=$(lstk aws kinesis get-shard-iterator --stream-name logtest --shard-id shardId-000000000000 --shard-iterator-type TRIM_HORIZON | jq -r .ShardIterator) +record=$(lstk aws kinesis get-records --limit 10 --shard-iterator $shard_iterator | jq -r '.Records[0].Data') echo $record | base64 -d | zcat ``` @@ -89,13 +89,13 @@ Metric filters can be used to automatically create CloudWatch metrics. In the following example we are interested in logs that include a key-value pair `"foo": "bar"` and create a metric filter. ```bash -awslocal logs create-log-group --log-group-name test-filter +lstk aws logs create-log-group --log-group-name test-filter -awslocal logs create-log-stream \ +lstk aws logs create-log-stream \ --log-group-name test-filter \ --log-stream-name test-filter-stream -awslocal logs put-metric-filter \ +lstk aws logs put-metric-filter \ --log-group-name test-filter \ --filter-name my-filter \ --filter-pattern "{$.foo = \"bar\"}" \ @@ -107,7 +107,7 @@ Next, we can insert some values: ```bash timestamp=$(($(date +'%s * 1000 + %-N / 1000000'))) -awslocal logs put-log-events --log-group-name test-filter \ +lstk aws logs put-log-events --log-group-name test-filter \ --log-stream-name test-filter-stream \ --log-events \ timestamp=$timestamp,message='"{\"foo\":\"bar\", \"hello\": \"world\"}"' \ @@ -119,7 +119,7 @@ Now we can check that the metric was indeed created: ```bash end=$(date +%s) -awslocal cloudwatch get-metric-statistics --namespace MyNamespace \ +lstk aws cloudwatch get-metric-statistics --namespace MyNamespace \ --metric-name MyMetric --statistics Sum --period 3600 \ --start-time 1659621274 --end-time $end ``` @@ -134,7 +134,7 @@ For purely JSON structured log messages, you can use JSON filter patterns to tra Enclose your pattern in curly braces, like this: ```bash -awslocal logs filter-log-events --log-group-name test-filter --filter-pattern "{$.foo = \"bar\"}" +lstk aws logs filter-log-events --log-group-name test-filter --filter-pattern "{$.foo = \"bar\"}" ``` This returns all events whose top level "foo" key has the "bar" value. @@ -145,7 +145,7 @@ You can use a simplified regex syntax for regular expression matching. Enclose your pattern in percentage signs like this: ```bash -awslocal logs filter-log-events --log-group-name test-filter --filter-pattern "\%[fF]oo\%" +lstk aws logs filter-log-events --log-group-name test-filter --filter-pattern "\%[fF]oo\%" ``` This returns all events containing "Foo" or "foo". @@ -156,7 +156,7 @@ For a complete set of the supported syntax, check [the official AWS documentatio If not specified otherwise in the pattern, we look for a match in the whole event message: ```bash -awslocal logs filter-log-events --log-group-name test-filter --filter-pattern "foo" +lstk aws logs filter-log-events --log-group-name test-filter --filter-pattern "foo" ``` ## Resource Browser diff --git a/src/content/docs/aws/services/managedblockchain.mdx b/src/content/docs/aws/services/managedblockchain.mdx index 90a00694e..e39d5acd9 100644 --- a/src/content/docs/aws/services/managedblockchain.mdx +++ b/src/content/docs/aws/services/managedblockchain.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to AMB and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to AMB and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a blockchain network, a node, and a proposal. @@ -28,7 +28,7 @@ You can create a blockchain network using the [`CreateNetwork`](https://docs.aws Run the following command to create a network named `OurBlockchainNet` which uses the Hyperledger Fabric with the following configuration: ```bash showshowLineNumbers -awslocal managedblockchain create-network \ +lstk aws managedblockchain create-network \ --cli-input-json '{ "Name": "OurBlockchainNet", "Description": "OurBlockchainNetDesc", @@ -83,7 +83,7 @@ You can create a node using the [`CreateNode`](https://docs.aws.amazon.com/manag Run the following command to create a node with the following configuration: ```bash showshowLineNumbers -awslocal managedblockchain create-node \ +lstk aws managedblockchain create-node \ --node-configuration '{ "InstanceType": "bc.t3.small", "AvailabilityZone": "us-east-1a", @@ -120,7 +120,7 @@ You can create a proposal using the [`CreateProposal`](https://docs.aws.amazon.c Run the following command to create a proposal with the following configuration: ```bash -awslocal managedblockchain create-proposal \ +lstk aws managedblockchain create-proposal \ --actions "Invitations=[{Principal=000000000000}]" \ --network-id n-X24AF1AK2GC6MDW11HYW5I5DQC \ --member-id m-6VWBWHP2Y15F7TQ2DS093RTCW2 diff --git a/src/content/docs/aws/services/mediaconvert.mdx b/src/content/docs/aws/services/mediaconvert.mdx index 1b4b566f8..3d103e3e8 100644 --- a/src/content/docs/aws/services/mediaconvert.mdx +++ b/src/content/docs/aws/services/mediaconvert.mdx @@ -20,7 +20,7 @@ Elemental MediaConvert is in a preview state. ## Getting started -This guide is designed for users new to Elemental MediaConvert and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Elemental MediaConvert and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a MediaConvert job, list jobs, create a queue, and list all queues using the AWS CLI. @@ -100,7 +100,7 @@ You can create a MediaConvert job using the [`CreateJob`](https://docs.aws.amazo Execute the following command to create a job using a `job.json` file: ```bash -awslocal mediaconvert create-job --cli-input-json file://job.json +lstk aws mediaconvert create-job --cli-input-json file://job.json ``` ```bash title="Output" @@ -148,7 +148,7 @@ You can list all MediaConvert jobs using the [`ListJobs`](https://docs.aws.amazo Execute the following command to list all jobs: ```bash -awslocal mediaconvert list-jobs +lstk aws mediaconvert list-jobs ``` ### Create a queue @@ -157,7 +157,7 @@ You can create a MediaConvert queue using the [`CreateQueue`](https://docs.aws.a Execute the following command to create a queue named `MyQueue`: ```bash -awslocal mediaconvert create-queue +lstk aws mediaconvert create-queue --name MyQueue --description "High priority queue for video encoding" ``` @@ -185,7 +185,7 @@ You can list all MediaConvert queues using the [`ListQueues`](https://docs.aws.a Execute the following command to list all queues: ```bash -awslocal mediaconvert list-queues +lstk aws mediaconvert list-queues ``` ## Current Limitations diff --git a/src/content/docs/aws/services/memorydb.mdx b/src/content/docs/aws/services/memorydb.mdx index d3c2af060..0f6543de5 100644 --- a/src/content/docs/aws/services/memorydb.mdx +++ b/src/content/docs/aws/services/memorydb.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to MemoryDB and assumes basic knowledge of the AWS CLI and our `awslocal` wrapper script. +This guide is designed for users new to MemoryDB and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how you can create a MemoryDB cluster and connect to it. @@ -28,7 +28,7 @@ You can create a MemoryDB cluster using the [`CreateCluster`](https://docs.aws.a Run the following command to create a cluster: ```bash -awslocal memorydb create-cluster \ +lstk aws memorydb create-cluster \ --cluster-name my-redis-cluster \ --node-type db.t4g.small \ --acl-name open-access @@ -38,7 +38,7 @@ Once it becomes available, you will be able to use the cluster endpoint for Redi Run the following command to retrieve the cluster endpoint using the [`DescribeClusters`](https://docs.aws.amazon.com/memorydb/latest/APIReference/API_DescribeClusters.html) API: ```bash -awslocal memorydb describe-clusters --query "Clusters[0].ClusterEndpoint" +lstk aws memorydb describe-clusters --query "Clusters[0].ClusterEndpoint" ``` ```bash title="Output" @@ -84,7 +84,7 @@ To enable full Valkey emulation: 2. Create a cluster with the Valkey engine by including the `--engine valkey` flag in your API call: ```bash -awslocal memorydb create-cluster \ +lstk aws memorydb create-cluster \ --cluster-name my-valkey-cluster \ --node-type db.t4g.small \ --acl-name open-access \ diff --git a/src/content/docs/aws/services/mq.mdx b/src/content/docs/aws/services/mq.mdx index 42b70ea2b..d0b188ed9 100644 --- a/src/content/docs/aws/services/mq.mdx +++ b/src/content/docs/aws/services/mq.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to MQ and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to MQ and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create an MQ broker and send a message to a sample queue. @@ -28,7 +28,7 @@ You can create a broker using the [`CreateBroker`](https://docs.aws.amazon.com/a Run the following command to create a broker named `test-broker` with the following configuration: ```bash -awslocal mq create-broker \ +lstk aws mq create-broker \ --broker-name test-broker \ --deployment-mode SINGLE_INSTANCE \ --engine-type ACTIVEMQ \ @@ -52,7 +52,7 @@ You can use the [`DescribeBroker`](https://docs.aws.amazon.com/amazon-mq/latest/ Run the following command to get information about the broker we created above: ```bash -awslocal mq describe-broker --broker-id b-f503abb7-66bc-47fb-b1a9-8d8c51ef6545 +lstk aws mq describe-broker --broker-id b-f503abb7-66bc-47fb-b1a9-8d8c51ef6545 ``` ```bash title="Output" diff --git a/src/content/docs/aws/services/mwaa.mdx b/src/content/docs/aws/services/mwaa.mdx index 19a010811..9d63a482a 100644 --- a/src/content/docs/aws/services/mwaa.mdx +++ b/src/content/docs/aws/services/mwaa.mdx @@ -16,7 +16,7 @@ The supported APIs are available on the [API Coverage section](#api-coverage). ## Getting started -This guide is designed for users new to MWAA and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to MWAA and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create an Airflow environment and access the Airflow UI. @@ -27,7 +27,7 @@ Create a S3 bucket that will be used for Airflow resources. Run the following command to create a bucket using the [`mb`](https://docs.aws.amazon.com/cli/latest/reference/s3/mb.html) command. ```bash -awslocal s3 mb s3://my-mwaa-bucket +lstk aws s3 mb s3://my-mwaa-bucket ``` ### Create an Airflow environment @@ -36,7 +36,7 @@ You can now create an Airflow environment, using the [`CreateEnvironment`](https Run the following command, by specifying the bucket ARN we created earlier: ```bash -awslocal mwaa create-environment --dag-s3-path /dags \ +lstk aws mwaa create-environment --dag-s3-path /dags \ --execution-role-arn arn:aws:iam::000000000000:role/airflow-role \ --network-configuration {} \ --source-bucket-arn arn:aws:s3:::my-mwaa-bucket \ @@ -51,7 +51,7 @@ The Airflow UI can be accessed via the URL in the `WebserverUrl` attribute of th The username and password are always set to `localstack`. ```bash -awslocal mwaa get-environment \ +lstk aws mwaa get-environment \ --name my-mwaa-env \ --query Environment.WebserverUrl \ "http://localhost.localstack.cloud:4510" @@ -97,7 +97,7 @@ Just upload your DAGs to the designated S3 bucket path, configured by the `DagS3 For example, the command below uploads a sample DAG named `sample_dag.py` to your S3 bucket named `my-mwaa-bucket`: ```bash -awslocal s3 cp sample_dag.py s3://my-mwaa-bucket/dags +lstk aws s3 cp sample_dag.py s3://my-mwaa-bucket/dags ``` LocalStack syncs new and changed objects in the S3 bucket to the Airflow container every 30 seconds. @@ -111,7 +111,7 @@ LocalStack seamlessly supports plugins packaged according to [AWS specifications To integrate your custom plugins into the MWAA environment, upload the packaged `plugins.zip` file to the designated S3 bucket path: ```bash -awslocal s3 cp plugins.zip s3://my-mwaa-bucket/plugins.zip +lstk aws s3 cp plugins.zip s3://my-mwaa-bucket/plugins.zip ``` ## Installing Python dependencies @@ -130,7 +130,7 @@ Once you have your `requirements.txt` file ready, upload it to the designated S3 Make sure to upload the file to `/requirements.txt` in the bucket: ```bash -awslocal s3 cp requirements.txt s3://my-mwaa-bucket/requirements.txt +lstk aws s3 cp requirements.txt s3://my-mwaa-bucket/requirements.txt ``` After the upload, the environment will be automatically updated, and your Apache Airflow setup will be equipped with the new dependencies. diff --git a/src/content/docs/aws/services/neptune.mdx b/src/content/docs/aws/services/neptune.mdx index 495ea9926..97b50da06 100644 --- a/src/content/docs/aws/services/neptune.mdx +++ b/src/content/docs/aws/services/neptune.mdx @@ -38,7 +38,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Neptune and assumes basic knowledge of the AWS CLI and our `awslocal` wrapper script. +This guide is designed for users new to Neptune and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate the following with AWS CLI & Python: @@ -53,7 +53,7 @@ To create a Neptune cluster you can use the [`CreateDBCluster`](https://docs.aws Run the following command to create a Neptune cluster: ```bash -awslocal neptune create-db-cluster \ +lstk aws neptune create-db-cluster \ --engine neptune \ --db-cluster-identifier my-neptune-db ``` @@ -76,7 +76,7 @@ To add an instance you can use the [`CreateDBInstance`](https://docs.aws.amazon. Run the following command to create a Neptune instance: ```bash -awslocal neptune create-db-instance \ +lstk aws neptune create-db-instance \ --db-cluster-identifier my-neptune-db \ --db-instance-identifier my-neptune-instance \ --engine neptune \ @@ -158,13 +158,13 @@ When LocalStack starts with [IAM enforcement enabled](/aws/developer-tools/secur Start LocalStack with `LOCALSTACK_ENFORCE_IAM=1` to create a Neptune cluster with IAM DB authentication enabled. ```bash -LOCALSTACK_ENFORCE_IAM=1 localstack start +LOCALSTACK_ENFORCE_IAM=1 lstk start ``` You can then create a cluster. ```bash -awslocal neptune create-db-cluster \ +lstk aws neptune create-db-cluster \ --engine neptune \ --db-cluster-identifier myneptune-db \ --enable-iam-database-authentication diff --git a/src/content/docs/aws/services/opensearch.mdx b/src/content/docs/aws/services/opensearch.mdx index 6dfea6f99..881a39424 100644 --- a/src/content/docs/aws/services/opensearch.mdx +++ b/src/content/docs/aws/services/opensearch.mdx @@ -39,7 +39,7 @@ You can select an Elasticsearch version with the `--engine-version` parameter wh ## Getting started -This guide is designed for users new to OpenSearch Service and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to OpenSearch Service and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a new OpenSearch Service cluster and interact with it, using the AWS CLI. @@ -51,7 +51,7 @@ OpenSearch Service domain is synonymous with an OpenSearch cluster. Execute the following command to create a new OpenSearch domain: ```bash -awslocal opensearch create-domain --domain-name my-domain +lstk aws opensearch create-domain --domain-name my-domain ``` Each time you establish a cluster using a new version of OpenSearch, the corresponding OpenSearch binary must be downloaded, a process that might require some time to complete. @@ -61,7 +61,7 @@ You can open the LocalStack logs, to see that the OpenSearch Service cluster is You can use the [`DescribeDomain`](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DescribeDomain.html) API to check the status of the cluster: ```bash -awslocal opensearch describe-domain \ +lstk aws opensearch describe-domain \ --domain-name my-domain | jq ".DomainStatus.Processing" ``` @@ -128,7 +128,7 @@ Moreover, you can opt for custom domains, though it's important to incorporate t Run the following command to create a new OpenSearch domain with a custom endpoint: ```bash -awslocal opensearch create-domain --domain-name my-domain \ +lstk aws opensearch create-domain --domain-name my-domain \ --domain-endpoint-options '{ "CustomEndpoint": "http://localhost:4566/my-custom-endpoint", "CustomEndpointEnabled": true }' ``` @@ -214,10 +214,10 @@ Save it in a file named `opensearch_domain.json`. } ``` -To provision it, use the following `awslocal` CLI command, assuming the aforementioned CLI input has been stored in a file named `opensearch_domain.json`: +To provision it, use the following `lstk aws` CLI command, assuming the aforementioned CLI input has been stored in a file named `opensearch_domain.json`: ```bash -awslocal opensearch create-domain --cli-input-json file://./opensearch_domain.json +lstk aws opensearch create-domain --cli-input-json file://./opensearch_domain.json ``` Once the domain setup is complete (`Processing: false`), the cluster can only be accessed with the given master user credentials, via HTTP basic authentication: @@ -243,17 +243,26 @@ When using OpenSearch Dashboards with LocalStack, you need to make sure to: - Ensure that the OpenSearch Dashboards Docker container uses the LocalStack DNS. You can find more information on how to connect your Docker container to Localstack in our [Network Troubleshooting guide](/aws/customization/networking/). -First, you need to make sure to start LocalStack in a specific Docker network: +First, you need to create a dedicated Docker network and start LocalStack within it (note: custom networks are not supported by the `lstk` CLI) ```bash -localstack start --network ls +docker network create ls + +docker run \ + -d --rm \ + --name localstack-main \ + --network ls \ + -p 127.0.0.1:4566:4566 \ + -p 127.0.0.1:4510-4559:4510-4559 \ + -v /var/run/docker.sock:/var/run/docker.sock \ + localstack/localstack ``` Now you can provision a new OpenSearch domain. Make sure to enable the [advanced security options](#advanced-security-options): ```bash -awslocal opensearch create-domain --cli-input-json file://./opensearch_domain.json +lstk aws opensearch create-domain --cli-input-json file://./opensearch_domain.json ``` Now you can start another container for OpenSearch Dashboards, which is configured such that: @@ -341,17 +350,17 @@ You can start the Docker Compose environment using the following command: docker-compose up -d ``` -You can now create an OpenSearch cluster using the `awslocal` CLI: +You can now create an OpenSearch cluster using the `lstk aws` CLI: ```bash -awslocal opensearch create-domain --domain-name my-domain +lstk aws opensearch create-domain --domain-name my-domain ``` If the `Processing` status shows as `true`, the cluster isn't fully operational yet. You can use the `describe-domain` command to retrieve the current status: ```bash -awslocal opensearch describe-domain --domain-name my-domain +lstk aws opensearch describe-domain --domain-name my-domain ``` You can now verify cluster health and set up indices: diff --git a/src/content/docs/aws/services/organizations.mdx b/src/content/docs/aws/services/organizations.mdx index d1ea226c1..50d76916e 100644 --- a/src/content/docs/aws/services/organizations.mdx +++ b/src/content/docs/aws/services/organizations.mdx @@ -17,49 +17,49 @@ Organizations is available over LocalStack for AWS and the supported APIs are av ## Getting started In this getting started guide, you'll learn how to create your local AWS Organization and configure it with member accounts. -This guide is intended for users who wish to get more acquainted with Organizations, and assumes you have basic knowledge of the AWS CLI (and our `awslocal` wrapper script). +This guide is intended for users who wish to get more acquainted with Organizations, and assumes you have basic knowledge of the AWS CLI (and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command). To get started, start your LocalStack instance using your preferred method: 1. Create a new local AWS Organization with the feature set flag set to `ALL`: ```bash - awslocal organizations create-organization --feature-set ALL + lstk aws organizations create-organization --feature-set ALL ``` 2. You can now run the `describe-organization` command to see the details of your organization: ```bash - awslocal organizations describe-organization + lstk aws organizations describe-organization ``` 3. You can now create an AWS account that would be a member of your organization: ```bash - awslocal organizations create-account \ + lstk aws organizations create-account \ --email example@example.com \ --account-name "Test Account" ``` Since LocalStack essentially mocks AWS, the account creation is instantaneous. You can now run the `list-accounts` command to see the details of your organization: ```bash - awslocal organizations list-accounts + lstk aws organizations list-accounts ``` 4. You can also remove a member account from your organization: ```bash - awslocal organizations remove-account-from-organization --account-id + lstk aws organizations remove-account-from-organization --account-id ``` 5. To close an account in your organization, you can run the `close-account` command: ```bash - awslocal organizations close-account --account-id 000000000000 + lstk aws organizations close-account --account-id 000000000000 ``` 6. You can use organizational units (OUs) to group accounts together to administer as a single unit. To create an OU, you can run: ```bash - awslocal organizations list-roots - awslocal organizations list-children \ + lstk aws organizations list-roots + lstk aws organizations list-children \ --parent-id \ --child-type ORGANIZATIONAL_UNIT - awslocal organizations create-organizational-unit \ + lstk aws organizations create-organizational-unit \ --parent-id \ --name New-Child-OU ``` @@ -67,25 +67,25 @@ To get started, start your LocalStack instance using your preferred method: 7. Before you can create and attach a policy to your organization, you must enable a policy type. To enable a policy type, you can run: ```bash - awslocal organizations enable-policy-type \ + lstk aws organizations enable-policy-type \ --root-id \ --policy-type SERVICE_CONTROL_POLICY ``` To disable a policy type, you can run: ```bash - awslocal organizations disable-policy-type \ + lstk aws organizations disable-policy-type \ --root-id \ --policy-type SERVICE_CONTROL_POLICY ``` 8. To view the policies that are attached to your organization, you can run: ```bash - awslocal organizations list-policies --filter SERVICE_CONTROL_POLICY + lstk aws organizations list-policies --filter SERVICE_CONTROL_POLICY ``` 9. To delete an organization, you can run: ```bash - awslocal organizations delete-organization + lstk aws organizations delete-organization ``` ## Service Control Policy enforcement @@ -116,7 +116,7 @@ Consider a member account that lists the objects of an S3 bucket in another acco ```bash # Run as the member (source) account -awslocal s3api list-objects-v2 --bucket cross-account-bucket +lstk aws s3api list-objects-v2 --bucket cross-account-bucket ``` The default `FullAWSAccess` SCP lets the request succeed on the bucket policy. @@ -140,7 +140,7 @@ You can use the [IAM Policy Simulator](https://docs.aws.amazon.com/IAM/latest/Us LocalStack evaluates SCPs during policy simulation, so you can validate SCP behavior with [`SimulatePrincipalPolicy`](https://docs.aws.amazon.com/IAM/latest/APIReference/API_SimulatePrincipalPolicy.html) before making live requests. ```bash -awslocal iam simulate-principal-policy \ +lstk aws iam simulate-principal-policy \ --policy-source-arn arn:aws:iam::111111111111:user/test \ --action-names s3:ListBucket \ --resource-arns arn:aws:s3:::cross-account-bucket @@ -178,7 +178,7 @@ LocalStack instead mirrors the behavior observed against real AWS: the enforced For example, the following policy is rejected because it includes a `Principal` element, which is not permitted in an SCP: ```bash -awslocal organizations create-policy \ +lstk aws organizations create-policy \ --name "InvalidSCP" \ --description "SCP with a Principal element" \ --type SERVICE_CONTROL_POLICY \ diff --git a/src/content/docs/aws/services/pinpoint.mdx b/src/content/docs/aws/services/pinpoint.mdx index cea967b24..fd3d93dce 100644 --- a/src/content/docs/aws/services/pinpoint.mdx +++ b/src/content/docs/aws/services/pinpoint.mdx @@ -22,7 +22,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Pinpoint and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Pinpoint and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a Pinpoint application, retrieve all applications, and list tags for the resource. @@ -33,7 +33,7 @@ Create a Pinpoint application using the [`CreateApp`](https://docs.aws.amazon.co Execute the following command: ```bash -awslocal pinpoint create-app \ +lstk aws pinpoint create-app \ --create-application-request Name=ExampleCorp,tags={"Stack"="Test"} ``` @@ -54,7 +54,7 @@ You can list all applications using the [`GetApps`](https://docs.aws.amazon.com/ Execute the following command: ```bash -awslocal pinpoint get-apps +lstk aws pinpoint get-apps ``` ```bash title="Output" @@ -78,7 +78,7 @@ You can list all tags for the application using the [`GetApp`](https://docs.aws. Execute the following command: ```bash -awslocal pinpoint list-tags-for-resource \ +lstk aws pinpoint list-tags-for-resource \ --resource-arn arn:aws:mobiletargeting:us-east-1:000000000000:apps/4487a55ac6fb4a2699a1b90727c978e7 ``` @@ -106,7 +106,7 @@ Instead it provides alternative ways to retrieve the actual OTP code as illustra Begin by making a OTP request: ```bash -awslocal pinpoint send-otp-message \ +lstk aws pinpoint send-otp-message \ --application-id fff5a801e01643c18a13a763e22a8fbf \ --send-otp-message-request-parameters '{ "BrandName": "LocalStack Pro", @@ -159,7 +159,7 @@ The OTP code is also printed in an `INFO` level message in the LocalStack log ou Finally, the OTP code can be verified using: ```bash -awslocal pinpoint verify-otp-message \ +lstk aws pinpoint verify-otp-message \ --application-id fff5a801e01643c18a13a763e22a8fbf \ --verify-otp-message-request-parameters '{ "ReferenceId": "liftoffcampaign", diff --git a/src/content/docs/aws/services/pipes.mdx b/src/content/docs/aws/services/pipes.mdx index 963d2d68a..acb565a6b 100644 --- a/src/content/docs/aws/services/pipes.mdx +++ b/src/content/docs/aws/services/pipes.mdx @@ -26,7 +26,7 @@ If you would like support for more APIs or report bugs, please make a request on ## Getting started -This guide is designed for users new to EventBridge Pipes and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to EventBridge Pipes and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a Pipe with SQS queues as source and target, and send events to the source queue which will be routed to the target queue. @@ -37,15 +37,15 @@ Create two SQS queues that will be used as source and target for the Pipe. Run the following command to create a queue using the [`CreateQueue`](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_CreateQueue.html) API: ```bash -awslocal sqs create-queue --queue-name source-queue -awslocal sqs create-queue --queue-name target-queue +lstk aws sqs create-queue --queue-name source-queue +lstk aws sqs create-queue --queue-name target-queue ``` You can fetch their queue ARNs using the [`GetQueueAttributes`](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_GetQueueAttributes.html) API: ```bash -SOURCE_QUEUE_ARN=$(awslocal sqs get-queue-attributes --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/source-queue --attribute-names QueueArn --output text) -TARGET_QUEUE_ARN=$(awslocal sqs get-queue-attributes --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/target-queue --attribute-names QueueArn --output text) +SOURCE_QUEUE_ARN=$(lstk aws sqs get-queue-attributes --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/source-queue --attribute-names QueueArn --output text) +TARGET_QUEUE_ARN=$(lstk aws sqs get-queue-attributes --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/target-queue --attribute-names QueueArn --output text) ``` ### Create a Pipe @@ -54,7 +54,7 @@ You can now create a Pipe, using the [`CreatePipe`](https://docs.aws.amazon.com/ Run the following command, by specifying the source and target queue ARNs we created earlier: ```bash -awslocal pipes create-pipe --name sample-pipe \ +lstk aws pipes create-pipe --name sample-pipe \ --source $SOURCE_QUEUE_ARN \ --target $TARGET_QUEUE_ARN \ --role-arn arn:aws:iam::000000000000:role/pipes-role @@ -76,7 +76,7 @@ awslocal pipes create-pipe --name sample-pipe \ You can use the [`DescribePipe`](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_DescribePipe.html) API to get information about the Pipe: ```bash -awslocal pipes describe-pipe --name sample-pipe +lstk aws pipes describe-pipe --name sample-pipe ``` ```bash title="Output" @@ -108,7 +108,7 @@ You can now send events to the source queue, which will be routed to the target Run the following command to send an event to the source queue: ```bash -awslocal sqs send-message \ +lstk aws sqs send-message \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/source-queue \ --message-body "message-1" ``` @@ -118,7 +118,7 @@ awslocal sqs send-message \ You can fetch the message from the target queue using the [`ReceiveMessage`](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) API: ```bash -awslocal sqs receive-message \ +lstk aws sqs receive-message \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/target-queue ``` diff --git a/src/content/docs/aws/services/ram.mdx b/src/content/docs/aws/services/ram.mdx index 79eaadbb0..c57b0b665 100644 --- a/src/content/docs/aws/services/ram.mdx +++ b/src/content/docs/aws/services/ram.mdx @@ -20,7 +20,7 @@ This section will illustrate how to create permissions and resource shares using ### Create a permission ```bash -awslocal ram create-permission \ +lstk aws ram create-permission \ --name example \ --resource-type appsync:apis \ --policy-template '{"Effect": "Allow", "Action": "appsync:SourceGraphQL"}' @@ -29,7 +29,7 @@ awslocal ram create-permission \ ### Create a resource share ```bash -awslocal ram create-resource-share \ +lstk aws ram create-resource-share \ --name example-resource-share \ --principals arn:aws:organizations::000000000000:organization/o-truopwybwi \ --resource-arn arn:aws:appsync:eu-central-1:000000000000:apis/wcgmjril5wuyvhmpildatuaat3 diff --git a/src/content/docs/aws/services/rds.mdx b/src/content/docs/aws/services/rds.mdx index 2f166fed5..6e954376e 100644 --- a/src/content/docs/aws/services/rds.mdx +++ b/src/content/docs/aws/services/rds.mdx @@ -26,7 +26,7 @@ Recreating the RDS state is recommended for compatibility. ## Getting started -This guide is designed for users new to RDS and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to RDS and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate the following with the AWS CLI: @@ -44,7 +44,7 @@ The following command creates a new cluster with the name `db1` and the engine ` Instances for the cluster must be added manually. ```bash -awslocal rds create-db-cluster \ +lstk aws rds create-db-cluster \ --db-cluster-identifier db1 \ --engine aurora-postgresql \ --database-name test \ @@ -67,7 +67,7 @@ awslocal rds create-db-cluster \ To add an instance you can run the following command: ```bash -awslocal rds create-db-instance \ +lstk aws rds create-db-instance \ --db-instance-identifier db1-instance \ --db-cluster-identifier db1 \ --engine aurora-postgresql \ @@ -96,7 +96,7 @@ EOF Run the following command to create the secret: ```bash -awslocal secretsmanager create-secret \ +lstk aws secretsmanager create-secret \ --name dbpass \ --secret-string file://mycreds.json ``` @@ -119,7 +119,7 @@ The following command executes a query against the database. The query returns the value `123`. ```bash -awslocal rds-data execute-statement \ +lstk aws rds-data execute-statement \ --database test \ --resource-arn arn:aws:rds:us-east-1:000000000000:cluster:db1 \ --secret-arn arn:aws:secretsmanager:us-east-1:000000000000:secret:dbpass-cfnAX \ @@ -260,7 +260,7 @@ The database will be created with a single instance, which will be used as the m MASTER_USER=hello MASTER_PW='MyPassw0rd!' DB_NAME=test -awslocal rds create-db-instance \ +lstk aws rds create-db-instance \ --master-username $MASTER_USER \ --master-user-password $MASTER_PW \ --db-instance-identifier mydb \ @@ -276,8 +276,8 @@ You can retrieve the hostname and port of your created instance either from the Run the following command to retrieve the host and port of the instance: ```bash -PORT=$(awslocal rds describe-db-instances --db-instance-identifier mydb | jq -r ".DBInstances[0].Endpoint.Port") -HOST=$(awslocal rds describe-db-instances --db-instance-identifier mydb | jq -r ".DBInstances[0].Endpoint.Address") +PORT=$(lstk aws rds describe-db-instances --db-instance-identifier mydb | jq -r ".DBInstances[0].Endpoint.Port") +HOST=$(lstk aws rds describe-db-instances --db-instance-identifier mydb | jq -r ".DBInstances[0].Endpoint.Address") ``` Next, you can connect to the database using the master username and password: @@ -292,7 +292,7 @@ PGPASSWORD=$MASTER_PW psql -d $DB_NAME -U $MASTER_USER -p $PORT -h $HOST -w -c ' You can create a token for the user you generated using the [`generate-db-auth-token`](https://docs.aws.amazon.com/cli/latest/reference/rds/generate-db-auth-token.html) command: ```bash -TOKEN=$(awslocal rds generate-db-auth-token --username myiam --hostname $HOST --port $PORT) +TOKEN=$(lstk aws rds generate-db-auth-token --username myiam --hostname $HOST --port $PORT) ``` You can now connect to the database utilizing the user you generated and the token obtained in the previous step as the password: diff --git a/src/content/docs/aws/services/redshift.mdx b/src/content/docs/aws/services/redshift.mdx index aefdba3b7..eeb73a25d 100644 --- a/src/content/docs/aws/services/redshift.mdx +++ b/src/content/docs/aws/services/redshift.mdx @@ -21,7 +21,7 @@ For advanced features like Redshift Data API and other emulation capabilities, p ## Getting started -This guide is designed for users new to RedShift and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to RedShift and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a RedShift cluster and database while using a Glue Crawler to populate the metadata store with the schema of the RedShift database tables using the AWS CLI. @@ -52,7 +52,7 @@ You can create a RedShift cluster using the [`CreateCluster`](https://docs.aws.a The following command will create a RedShift cluster with the variables defined above: ```bash -awslocal redshift create-cluster \ +lstk aws redshift create-cluster \ --cluster-identifier $REDSHIFT_CLUSTER_IDENTIFIER \ --db-name $REDSHIFT_DATABASE_NAME \ --master-username $REDSHIFT_USERNAME \ @@ -64,7 +64,7 @@ You can fetch the status of the cluster using the [`DescribeClusters`](https://d Run the following command to extract the URL of the cluster: ```bash -REDSHIFT_URL=$(awslocal redshift describe-clusters \ +REDSHIFT_URL=$(lstk aws redshift describe-clusters \ --cluster-identifier $REDSHIFT_CLUSTER_IDENTIFIER | jq -r '(.Clusters[0].Endpoint.Address) + ":" + (.Clusters[0].Endpoint.Port|tostring)') ``` @@ -74,7 +74,7 @@ You can create a Glue database using the [`CreateDatabase`](https://docs.aws.ama The following command will create a Glue database: ```bash -awslocal glue create-database \ +lstk aws glue create-database \ --database-input "{\"Name\": \"$GLUE_DATABASE_NAME\"}" ``` @@ -82,7 +82,7 @@ You can create a connection to the RedShift cluster using the [`CreateConnection The following command will create a Glue connection with the RedShift cluster: ```bash -awslocal glue create-connection \ +lstk aws glue create-connection \ --connection-input "{\"Name\":\"$GLUE_CONNECTION_NAME\", \"ConnectionType\": \"JDBC\", \"ConnectionProperties\": {\"USERNAME\": \"$REDSHIFT_USERNAME\", \"PASSWORD\": \"$REDSHIFT_PASSWORD\", \"JDBC_CONNECTION_URL\": \"jdbc:redshift://$REDSHIFT_URL/$REDSHIFT_DATABASE_NAME\"}}" ``` @@ -90,7 +90,7 @@ Finally, you can create a Glue crawler using the [`CreateCrawler`](https://docs. The following command will create a Glue crawler: ```bash -awslocal glue create-crawler \ +lstk aws glue create-crawler \ --name $GLUE_CRAWLER_NAME \ --database-name $GLUE_DATABASE_NAME \ --targets "{\"JdbcTargets\": [{\"ConnectionName\": \"$GLUE_CONNECTION_NAME\", \"Path\": \"$REDSHIFT_DATABASE_NAME/%/$REDSHIFT_TABLE_NAME\"}]}" \ @@ -103,7 +103,7 @@ You can create a table in RedShift using the [`CreateTable`](https://docs.aws.am The following command will create a table in RedShift: ```bash -REDSHIFT_STATEMENT_ID=$(awslocal redshift-data execute-statement \ +REDSHIFT_STATEMENT_ID=$(lstk aws redshift-data execute-statement \ --cluster-identifier $REDSHIFT_CLUSTER_IDENTIFIER \ --database $REDSHIFT_DATABASE_NAME \ --sql \ @@ -114,7 +114,7 @@ You can check the status of the statement using the [`DescribeStatement`](https: The following command will check the status of the statement: ```bash -wait "awslocal redshift-data describe-statement \ +wait "lstk aws redshift-data describe-statement \ --id $REDSHIFT_STATEMENT_ID" ".Status" "FINISHED" ``` @@ -124,7 +124,7 @@ You can run the crawler using the [`StartCrawler`](https://docs.aws.amazon.com/g The following command will run the crawler: ```bash -awslocal glue start-crawler \ +lstk aws glue start-crawler \ --name $GLUE_CRAWLER_NAME ``` @@ -132,7 +132,7 @@ You can wait for the crawler to finish using the [`GetCrawler`](https://docs.aws The following command will wait for the crawler to finish: ```bash -wait "awslocal glue get-crawler \ +wait "lstk aws glue get-crawler \ --name $GLUE_CRAWLER_NAME" ".Crawler.State" "READY" ``` @@ -140,7 +140,7 @@ You can finally retrieve the schema of the table using the [`GetTable`](https:// The following command will retrieve the schema of the table: ```bash -awslocal glue get-table \ +lstk aws glue get-table \ --database-name $GLUE_DATABASE_NAME \ --name "${REDSHIFT_DATABASE_NAME}_${REDSHIFT_SCHEMA_NAME}_${REDSHIFT_TABLE_NAME}" ``` diff --git a/src/content/docs/aws/services/resource-groups-tagging-api.mdx b/src/content/docs/aws/services/resource-groups-tagging-api.mdx index d268702c1..039744e29 100644 --- a/src/content/docs/aws/services/resource-groups-tagging-api.mdx +++ b/src/content/docs/aws/services/resource-groups-tagging-api.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Resource Groups Tagging API and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Resource Groups Tagging API and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create resources, tag them, and query them using the Resource Groups Tagging API. @@ -30,15 +30,15 @@ Create an S3 bucket and an SQS queue: BUCKET_NAME="rg-tagging-bucket" QUEUE_NAME="rg-tagging-queue" -awslocal s3api create-bucket --bucket "$BUCKET_NAME" -QUEUE_URL=$(awslocal sqs create-queue --queue-name "$QUEUE_NAME" | jq -r '.QueueUrl') +lstk aws s3api create-bucket --bucket "$BUCKET_NAME" +QUEUE_URL=$(lstk aws sqs create-queue --queue-name "$QUEUE_NAME" | jq -r '.QueueUrl') ``` Retrieve the resource ARNs: ```bash BUCKET_ARN="arn:aws:s3:::$BUCKET_NAME" -QUEUE_ARN=$(awslocal sqs get-queue-attributes \ +QUEUE_ARN=$(lstk aws sqs get-queue-attributes \ --queue-url "$QUEUE_URL" \ --attribute-names QueueArn | jq -r '.Attributes.QueueArn') ``` @@ -48,7 +48,7 @@ QUEUE_ARN=$(awslocal sqs get-queue-attributes \ Use the [`TagResources`](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/API_TagResources.html) API to apply tags: ```bash -awslocal resourcegroupstaggingapi tag-resources \ +lstk aws resourcegroupstaggingapi tag-resources \ --resource-arn-list "$BUCKET_ARN" "$QUEUE_ARN" \ --tags '{"Environment":"dev","Team":"platform"}' ``` @@ -58,15 +58,15 @@ awslocal resourcegroupstaggingapi tag-resources \ Use the [`GetResources`](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/API_GetResources.html) API to list resources with a specific tag: ```bash -awslocal resourcegroupstaggingapi get-resources \ +lstk aws resourcegroupstaggingapi get-resources \ --tag-filters Key=Environment,Values=dev ``` You can also inspect available keys and values: ```bash -awslocal resourcegroupstaggingapi get-tag-keys -awslocal resourcegroupstaggingapi get-tag-values --key Environment +lstk aws resourcegroupstaggingapi get-tag-keys +lstk aws resourcegroupstaggingapi get-tag-values --key Environment ``` ### Remove tags from resources @@ -74,7 +74,7 @@ awslocal resourcegroupstaggingapi get-tag-values --key Environment Use the [`UntagResources`](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/API_UntagResources.html) API to remove one or more tag keys: ```bash -awslocal resourcegroupstaggingapi untag-resources \ +lstk aws resourcegroupstaggingapi untag-resources \ --resource-arn-list "$BUCKET_ARN" "$QUEUE_ARN" \ --tag-keys Team ``` diff --git a/src/content/docs/aws/services/resource-groups.mdx b/src/content/docs/aws/services/resource-groups.mdx index 4e6366711..bcf30d705 100644 --- a/src/content/docs/aws/services/resource-groups.mdx +++ b/src/content/docs/aws/services/resource-groups.mdx @@ -20,7 +20,7 @@ For tag-centric operations across AWS resources, see the [Resource Groups Taggin ## Getting Started -This guide is designed for users new to Resource Groups and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Resource Groups and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a Resource Group using the AWS CLI. @@ -37,7 +37,7 @@ Use the [`CreateGroup`](https://docs.aws.amazon.com/resource-groups/latest/APIRe Run the following command to create a Resource Group named `my-resource-group`: ```bash -awslocal resource-groups create-group \ +lstk aws resource-groups create-group \ --name my-resource-group \ --resource-query '{"Type":"TAG_FILTERS_1_0","Query":"{\"ResourceTypeFilters\":[\"AWS::EC2::Instance\"],\"TagFilters\":[{\"Key\":\"Stage\",\"Values\":[\"Test\"]}]}"}' ``` @@ -50,7 +50,7 @@ To update a Resource Group, use the [`UpdateGroup`](https://docs.aws.amazon.com/ Execute the following command to update the Resource Group `my-resource-group`: ```bash -awslocal resource-groups update-group \ +lstk aws resource-groups update-group \ --group-name my-resource-group \ --description "EC2 S3 buckets and RDS DBs that we are using for the test stage" ``` @@ -59,7 +59,7 @@ Furthermore, you can also update the query and tags associated with a Resource G Run the following command to update the query and tags of the Resource Group `my-resource-group`: ```bash -awslocal resource-groups update-group-query \ +lstk aws resource-groups update-group-query \ --group-name my-resource-group \ --resource-query '{"Type":"TAG_FILTERS_1_0","Query":"{\"ResourceTypeFilters\":[\"AWS::EC2::Instance\",\"AWS::S3::Bucket\",\"AWS::RDS::DBInstance\"],\"TagFilters\":[{\"Key\":\"Stage\",\"Values\":[\"Test\"]}]}"}' ``` @@ -70,7 +70,7 @@ To delete a Resource Group, use the [`DeleteGroup`](https://docs.aws.amazon.com/ Run the following command to delete the Resource Group `my-resource-group`: ```bash -awslocal resource-groups delete-group \ +lstk aws resource-groups delete-group \ --group-name my-resource-group ``` diff --git a/src/content/docs/aws/services/route53.mdx b/src/content/docs/aws/services/route53.mdx index 588ed5f6c..64bbde4d4 100644 --- a/src/content/docs/aws/services/route53.mdx +++ b/src/content/docs/aws/services/route53.mdx @@ -20,14 +20,23 @@ LocalStack supports routing traffic to various AWS resources including [S3 stati LocalStack also integrates with its DNS server to respond to DNS queries with these domains. :::note -LocalStack CLI does not publish port `53` anymore by default. -Use the CLI flag `--host-dns` to expose the port on the host. -This would be required if you want to reach out to Route53 domain names from your host machine, using the LocalStack DNS server. +`lstk` does not publish port `53` on the host by default. +Add `expose_ports = [53]` to the container block in your `config.toml` to expose it: + +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +expose_ports = [53] +``` + +This is required if you want to reach out to Route53 domain names from your host machine, using the LocalStack DNS server. +See [System DNS configuration](/aws/customization/networking/dns-server#system-dns-configuration) for details. ::: ## Getting started -This guide is designed for users new to Route53 and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Route53 and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a hosted zone and query the DNS record with the AWS CLI. @@ -38,7 +47,7 @@ You can created a hosted zone for `example.com` using the [`CreateHostedZone`](h Run the following command: ```bash -zone_id=$(awslocal route53 create-hosted-zone \ +zone_id=$(lstk aws route53 create-hosted-zone \ --name example.com \ --caller-reference r1 | jq -r '.HostedZone.Id') echo $zone_id @@ -54,7 +63,7 @@ You can now change the resource record sets for the hosted zone `example.com` us Run the following command: ```bash -awslocal route53 change-resource-record-sets \ +lstk aws route53 change-resource-record-sets \ --hosted-zone-id $zone_id \ --change-batch 'Changes=[{Action=CREATE,ResourceRecordSet={Name=test.example.com,Type=A,ResourceRecords=[{Value=1.2.3.4}]}}]' ``` @@ -82,19 +91,19 @@ DOMAIN="example.com" BUCKET_NAME="$DOMAIN" # Create the bucket -awslocal s3api create-bucket --bucket "$BUCKET_NAME" +lstk aws s3api create-bucket --bucket "$BUCKET_NAME" # Upload your website files -awslocal s3 cp index.html s3://$BUCKET_NAME/ -awslocal s3 cp error.html s3://$BUCKET_NAME/ +lstk aws s3 cp index.html s3://$BUCKET_NAME/ +lstk aws s3 cp error.html s3://$BUCKET_NAME/ # Configure the bucket for website hosting -awslocal s3 website s3://"$BUCKET_NAME"/ \ +lstk aws s3 website s3://"$BUCKET_NAME"/ \ --index-document index.html \ --error-document error.html # Set bucket policy to allow public read access -awslocal s3api put-bucket-policy \ +lstk aws s3api put-bucket-policy \ --bucket $BUCKET_NAME \ --policy '{ "Version": "2012-10-17", @@ -114,7 +123,7 @@ Now create a hosted zone and an alias record that points to the S3 website endpo ```bash # Create the hosted zone -HOSTED_ZONE_ID=$(awslocal route53 create-hosted-zone \ +HOSTED_ZONE_ID=$(lstk aws route53 create-hosted-zone \ --name "$DOMAIN" \ --caller-reference "$(date +%s)" \ --output text \ @@ -123,7 +132,7 @@ HOSTED_ZONE_ID=$(awslocal route53 create-hosted-zone \ echo "Hosted Zone created with ID: $HOSTED_ZONE_ID" # Create an alias record pointing to the S3 website endpoint -awslocal route53 change-resource-record-sets \ +lstk aws route53 change-resource-record-sets \ --hosted-zone-id "$HOSTED_ZONE_ID" \ --change-batch '{ "Comment": "Create alias record for S3 static website", @@ -171,7 +180,7 @@ After creating your load balancer, you can create an alias record that points to ELB_DNS_NAME="my-load-balancer-123456.elb.localhost.localstack.cloud" # Create an alias record pointing to the ELB -awslocal route53 change-resource-record-sets \ +lstk aws route53 change-resource-record-sets \ --hosted-zone-id "$HOSTED_ZONE_ID" \ --change-batch '{ "Comment": "Create alias record for ELB", @@ -239,7 +248,7 @@ Create a hosted zone for the domain `localhost.localstack.cloud` using the [`Cre Run the following command: ```bash -zone_id=$(awslocal route53 create-hosted-zone \ +zone_id=$(lstk aws route53 create-hosted-zone \ --name localhost.localstack.cloud \ --caller-reference r1 | jq -r .HostedZone.Id) echo $zone_id @@ -253,7 +262,7 @@ You can now use the [`ChangeResourceRecordSets`](https://docs.aws.amazon.com/Rou Run the following command to accomplish this: ```bash -awslocal route53 change-resource-record-sets \ +lstk aws route53 change-resource-record-sets \ --hosted-zone-id $zone_id \ --change-batch '{"Changes":[{"Action":"CREATE","ResourceRecordSet":{"Name":"localhost.localstack.cloud","Type":"A","ResourceRecords":[{"Value":"5.6.7.8"}]}},{"Action":"CREATE","ResourceRecordSet":{"Name":"*.localhost.localstack.cloud","Type":"A","ResourceRecords":[{"Value":"5.6.7.8"}]}}]}' ``` diff --git a/src/content/docs/aws/services/route53resolver.mdx b/src/content/docs/aws/services/route53resolver.mdx index 93e4cbd8e..c03717e57 100644 --- a/src/content/docs/aws/services/route53resolver.mdx +++ b/src/content/docs/aws/services/route53resolver.mdx @@ -18,7 +18,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Route53 Resolver and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Route53 Resolver and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a resolver endpoint, list the endpoints, and delete the endpoint with the AWS CLI. @@ -28,13 +28,13 @@ We will demonstrate how to create a resolver endpoint, list the endpoints, and d Fetch the default VPC ID using the following command: ```bash -VPC_ID=$(awslocal ec2 describe-vpcs --query 'Vpcs[?IsDefault==`true`].VpcId' --output text) +VPC_ID=$(lstk aws ec2 describe-vpcs --query 'Vpcs[?IsDefault==`true`].VpcId' --output text) ``` Fetch the default VPC's security group ID using the following command: ```bash -awslocal ec2 describe-subnets --filters Name=vpc-id,Values=$VPC_ID --query 'Subnets[].SubnetId' +lstk aws ec2 describe-subnets --filters Name=vpc-id,Values=$VPC_ID --query 'Subnets[].SubnetId' ``` ```bash title="Output" @@ -51,7 +51,7 @@ awslocal ec2 describe-subnets --filters Name=vpc-id,Values=$VPC_ID --query 'Subn Choose two subnets from the list above and fetch the CIDR block of the subnets which tells you the range of IP addresses within it. Let's fetch the CIDR block of the subnet `subnet-957d6ba6`: ```bash -awslocal ec2 describe-subnets --subnet-ids subnet-957d6ba6 --query 'Subnets[*].CidrBlock' +lstk aws ec2 describe-subnets --subnet-ids subnet-957d6ba6 --query 'Subnets[*].CidrBlock' ``` ```bash title="Output" @@ -63,7 +63,7 @@ awslocal ec2 describe-subnets --subnet-ids subnet-957d6ba6 --query 'Subnets[*].C Similarly, fetch the CIDR block of the subnet `subnet-bdd58a47`: ```bash -awslocal ec2 describe-subnets --subnet-ids subnet-bdd58a47 --query 'Subnets[*].CidrBlock' +lstk aws ec2 describe-subnets --subnet-ids subnet-bdd58a47 --query 'Subnets[*].CidrBlock' ``` ```bash title="Output" @@ -76,7 +76,7 @@ Save the CIDR blocks of the subnets as you will need them later. Lastly fetch the security group ID of the default VPC: ```bash -awslocal ec2 describe-security-groups \ +lstk aws ec2 describe-security-groups \ --filters Name=vpc-id,Values=$VPC_ID \ --query 'SecurityGroups[0].GroupId' ``` @@ -122,7 +122,7 @@ You can now use the [`CreateResolverEndpoint`](https://docs.aws.amazon.com/Route Run the following command: ```bash -awslocal route53resolver create-resolver-endpoint \ +lstk aws route53resolver create-resolver-endpoint \ --cli-input-json file://create-outbound-resolver-endpoint.json ``` @@ -153,7 +153,7 @@ You can list the resolver endpoints using the [`ListResolverEndpoints`](https:// Run the following command: ```bash -awslocal route53resolver list-resolver-endpoints +lstk aws route53resolver list-resolver-endpoints ``` ```bash title="Output" @@ -186,7 +186,7 @@ You can delete the resolver endpoint using the [`DeleteResolverEndpoint`](https: Run the following command: ```bash -awslocal route53resolver delete-resolver-endpoint \ +lstk aws route53resolver delete-resolver-endpoint \ --resolver-endpoint-id rslvr-out-5d61abaff9de06b99 ``` diff --git a/src/content/docs/aws/services/s3.mdx b/src/content/docs/aws/services/s3.mdx index c3cb15372..b13b9dfce 100644 --- a/src/content/docs/aws/services/s3.mdx +++ b/src/content/docs/aws/services/s3.mdx @@ -19,7 +19,7 @@ The supported APIs are available on the API coverage section for [S3](#api-cover ## Getting started -This guide is designed for users new to S3 and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to S3 and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how you can create an S3 bucket, manage S3 objects, and generate pre-signed URLs for S3 objects. @@ -30,14 +30,14 @@ You can create an S3 bucket using the [`CreateBucket`](https://docs.aws.amazon.c Run the following command to create an S3 bucket named `sample-bucket`: ```bash -awslocal s3api create-bucket --bucket sample-bucket +lstk aws s3api create-bucket --bucket sample-bucket ``` You can list your S3 buckets using the [`ListBuckets`](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-buckets.html) API. Run the following command to list your S3 buckets: ```bash -awslocal s3api list-buckets +lstk aws s3api list-buckets ``` ```bash title="Output" @@ -62,7 +62,7 @@ Download a random image from the internet and save it as `image.jpg`. Run the following command to upload the file to your S3 bucket: ```bash -awslocal s3api put-object \ +lstk aws s3api put-object \ --bucket sample-bucket \ --key image.jpg \ --body image.jpg @@ -72,7 +72,7 @@ You can list the objects in your S3 bucket using the [`ListObjects`](https://doc Run the following command to list the objects in your S3 bucket: ```bash -awslocal s3api list-objects \ +lstk aws s3api list-objects \ --bucket sample-bucket ``` @@ -99,7 +99,7 @@ If your image has been uploaded successfully, you will see the following output: Run the following command to upload a file named `index.html` to your S3 bucket: ```bash -awslocal s3api put-object --bucket sample-bucket --key index.html --body index.html +lstk aws s3api put-object --bucket sample-bucket --key index.html --body index.html ``` ```bash title="Output" @@ -116,7 +116,7 @@ Pre-signed URL allows anyone to retrieve the S3 object with an HTTP GET request. Run the following command to generate a pre-signed URL for your S3 object: ```bash -awslocal s3 presign s3://sample-bucket/image.jpg +lstk aws s3 presign s3://sample-bucket/image.jpg ``` You will see a generated pre-signed URL for your S3 object. @@ -161,7 +161,7 @@ It would allow your local application to communicate directly with an S3 bucket By default, LocalStack will apply specific CORS rules to all requests to allow you to display and access your resources through [LocalStack Web Application](https://app.localstack.cloud). If no CORS rules are configured for your S3 bucket, LocalStack will apply default rules unless specified otherwise. -To configure CORS rules for your S3 bucket, you can use the `awslocal` wrapper. +To configure CORS rules for your S3 bucket, you can use the `lstk aws` command. Optionally, you can run a local web application on [localhost:3000](http://localhost:3000). You can emulate the same behaviour with an AWS SDK or an integration you use. Follow this step-by-step guide to configure CORS rules on your S3 bucket. @@ -169,7 +169,7 @@ Follow this step-by-step guide to configure CORS rules on your S3 bucket. Run the following command on your terminal to create your S3 bucket: ```bash -awslocal s3api create-bucket --bucket cors-bucket +lstk aws s3api create-bucket --bucket cors-bucket ``` ```bash title="Output" @@ -202,13 +202,13 @@ Save the file locally with a name of your choice, for example, `cors-config.json Run the following command to apply the CORS configuration to your S3 bucket: ```bash -awslocal s3api put-bucket-cors --bucket cors-bucket --cors-configuration file://cors-config.json +lstk aws s3api put-bucket-cors --bucket cors-bucket --cors-configuration file://cors-config.json ``` You can further verify that the CORS configuration was applied successfully by running the following command: ```bash -awslocal s3api get-bucket-cors --bucket cors-bucket +lstk aws s3api get-bucket-cors --bucket cors-bucket ``` On applying the configuration successfully, you should see the same JSON configuration file you created earlier. @@ -237,8 +237,8 @@ We can edit the JSON file `cors-config.json` you created earlier with the follow You can now run the same steps as before to update the CORS configuration and verify if it is applied correctly: ```bash -awslocal s3api put-bucket-cors --bucket cors-bucket --cors-configuration file://cors-config.json -awslocal s3api get-bucket-cors --bucket cors-bucket +lstk aws s3api put-bucket-cors --bucket cors-bucket --cors-configuration file://cors-config.json +lstk aws s3api get-bucket-cors --bucket cors-bucket ``` You can try again to upload files in your bucket from the [LocalStack Web Application](https://app.localstack.cloud) and it should work. diff --git a/src/content/docs/aws/services/s3tables.mdx b/src/content/docs/aws/services/s3tables.mdx index 4b472186b..34bb68742 100644 --- a/src/content/docs/aws/services/s3tables.mdx +++ b/src/content/docs/aws/services/s3tables.mdx @@ -18,7 +18,7 @@ The supported APIs are available on the [API coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to S3 Tables and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to S3 Tables and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a table bucket, a namespace, a table, and how to retrieve table details and metadata location with the AWS CLI. @@ -30,7 +30,7 @@ You can create a table bucket to store S3 Tables using the [`CreateTableBucket`] Run the following command to create a table bucket named `my-table-bucket`: ```bash -awslocal s3tables create-table-bucket --name my-table-bucket +lstk aws s3tables create-table-bucket --name my-table-bucket ``` ```bash title="Output" @@ -46,7 +46,7 @@ Namespaces help organize tables within a table bucket. You can create a namespac Run the following command to create a namespace named `my_namespace` within the table bucket `my-table-bucket`: ```bash -awslocal s3tables create-namespace \ +lstk aws s3tables create-namespace \ --table-bucket-arn arn:aws:s3tables:us-east-1:000000000000:bucket/my-table-bucket \ --namespace my_namespace ``` @@ -67,7 +67,7 @@ You can also create a table within the namespace with the [`CreateTable`](https: Run the following command to create a table named `my_table` within the namespace `my_namespace`: ```bash -awslocal s3tables create-table \ +lstk aws s3tables create-table \ --table-bucket-arn arn:aws:s3tables:us-east-1:000000000000:bucket/my-table-bucket \ --namespace my_namespace \ --name my_table \ @@ -88,7 +88,7 @@ You can describe the table to view details such as ARN, namespace, format, and w Run the following command to describe the table `my_table`: ```bash -awslocal s3tables get-table \ +lstk aws s3tables get-table \ --table-bucket-arn arn:aws:s3tables:us-east-1:000000000000:bucket/my-table-bucket \ --namespace my_namespace \ --name my_table @@ -121,7 +121,7 @@ You can fetch the warehouse location used for table metadata using the [`GetTabl Run the following command to fetch the warehouse location for the table `my_table`: ```bash -awslocal s3tables get-table-metadata-location \ +lstk aws s3tables get-table-metadata-location \ --table-bucket-arn arn:aws:s3tables:us-east-1:000000000000:bucket/my-table-bucket \ --namespace my_namespace \ --name my_table @@ -142,7 +142,7 @@ You can list tables in the `my_namespace` namespace using the [`ListTables`](htt Run the following command to list tables in the namespace `my_namespace`: ```bash -awslocal s3tables list-tables \ +lstk aws s3tables list-tables \ --table-bucket-arn arn:aws:s3tables:us-east-1:000000000000:bucket/my-table-bucket \ --namespace my_namespace ``` diff --git a/src/content/docs/aws/services/scheduler.mdx b/src/content/docs/aws/services/scheduler.mdx index 9230fa006..fc3557f7c 100644 --- a/src/content/docs/aws/services/scheduler.mdx +++ b/src/content/docs/aws/services/scheduler.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to EventBridge Scheduler and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to EventBridge Scheduler and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how you can create a new schedule, list all schedules, and tag a schedule using the EventBridge Scheduler APIs. @@ -28,14 +28,14 @@ You can create a new SQS queue using the [`CreateQueue`](https://docs.aws.amazon Run the following command to create a new SQS queue: ```bash -awslocal sqs create-queue --queue-name local-notifications +lstk aws sqs create-queue --queue-name local-notifications ``` You can fetch the Queue ARN using the [`GetQueueAttributes`](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_GetQueueAttributes.html) API. Run the following command to fetch the Queue ARN by specifying the Queue URL: ```bash -awslocal sqs get-queue-attributes \ +lstk aws sqs get-queue-attributes \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/local-notifications \ --attribute-names All ``` @@ -48,7 +48,7 @@ You can create a new schedule using the [`CreateSchedule`](https://docs.aws.amaz Run the following command to create a new schedule: ```bash -awslocal scheduler create-schedule \ +lstk aws scheduler create-schedule \ --name sqs-templated-schedule \ --schedule-expression 'rate(5 minutes)' \ --target '{"RoleArn": "arn:aws:iam::000000000000:role/schedule-role", "Arn":"arn:aws:sqs:us-east-1:000000000000:local-notifications", "Input": "test" }' \ @@ -67,7 +67,7 @@ You can list all schedules using the [`ListSchedules`](https://docs.aws.amazon.c Run the following command to list all schedules: ```bash -awslocal scheduler list-schedules +lstk aws scheduler list-schedules ``` ```bash title="Output" @@ -94,7 +94,7 @@ You can tag a schedule using the [`TagResource`](https://docs.aws.amazon.com/eve Run the following command to tag a schedule: ```bash -awslocal scheduler tag-resource \ +lstk aws scheduler tag-resource \ --resource-arn arn:aws:scheduler:us-east-1:000000000000:schedule/default/sqs-templated-schedule \ --tags Key=Name,Value=Test ``` @@ -103,7 +103,7 @@ You can view the tags associated with a schedule using the [`ListTagsForResource Run the following command to list the tags associated with a schedule: ```bash -awslocal scheduler list-tags-for-resource \ +lstk aws scheduler list-tags-for-resource \ --resource-arn arn:aws:scheduler:us-east-1:00000000 ```bash title="Output" diff --git a/src/content/docs/aws/services/secretsmanager.mdx b/src/content/docs/aws/services/secretsmanager.mdx index 837573718..73458e30d 100644 --- a/src/content/docs/aws/services/secretsmanager.mdx +++ b/src/content/docs/aws/services/secretsmanager.mdx @@ -18,7 +18,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Secrets Manager and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Secrets Manager and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a secret, get the secret value, and rotate the secret using the AWS CLI. @@ -41,7 +41,7 @@ You can now create a secret using the [`CreateSecret`](https://docs.aws.amazon.c Execute the following command to create a secret named `test-secret`: ```bash -awslocal secretsmanager create-secret \ +lstk aws secretsmanager create-secret \ --name test-secret \ --description "LocalStack Secret" \ --secret-string file://secrets.json @@ -64,7 +64,7 @@ To retrieve the details of the secret you created earlier, you can use the [`Des Execute the following command: ```bash -awslocal secretsmanager describe-secret \ +lstk aws secretsmanager describe-secret \ --secret-id test-secret ``` @@ -87,7 +87,7 @@ You can also get a list of the secrets available in your local environment that Execute the following command: ```bash -awslocal secretsmanager list-secrets \ +lstk aws secretsmanager list-secrets \ --filters Key=name,Values=Secret ``` @@ -97,7 +97,7 @@ To retrieve the value of the secret you created earlier, you can use the [`GetSe Execute the following command: ```bash -awslocal secretsmanager get-secret-value \ +lstk aws secretsmanager get-secret-value \ --secret-id test-secret ``` @@ -118,7 +118,7 @@ You can tag your secret using the [`TagResource`](https://docs.aws.amazon.com/se Execute the following command: ```bash -awslocal secretsmanager tag-resource \ +lstk aws secretsmanager tag-resource \ --secret-id test-secret \ --tags Key=Environment,Value=Development ``` @@ -133,7 +133,7 @@ Execute the following command: ```bash zip my-function.zip lambda_function.py -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name my-rotation-function \ --runtime python3.9 \ --zip-file fileb://my-function.zip \ @@ -148,7 +148,7 @@ Please note that this is not required with the default LocalStack settings, sinc Execute the following command: ```bash -awslocal lambda add-permission \ +lstk aws lambda add-permission \ --function-name my-rotation-function \ --action lambda:InvokeFunction \ --statement-id SecretsManager \ @@ -159,7 +159,7 @@ You can now create a rotation schedule for the secret using the [`RotateSecret`] Execute the following command: ```bash -awslocal secretsmanager rotate-secret \ +lstk aws secretsmanager rotate-secret \ --secret-id MySecret \ --rotation-lambda-arn arn:aws:lambda:us-east-1:000000000000:function:my-rotation-function \ --rotation-rules "{\"ScheduleExpression\": \"cron(0 16 1,15 *?*)\", \"Duration\": \"2h\"}" diff --git a/src/content/docs/aws/services/serverlessrepo.mdx b/src/content/docs/aws/services/serverlessrepo.mdx index 785ebd361..003bdc58f 100644 --- a/src/content/docs/aws/services/serverlessrepo.mdx +++ b/src/content/docs/aws/services/serverlessrepo.mdx @@ -17,17 +17,17 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Serverless Application Repository and assumes basic knowledge of the SAM CLI and our [`samlocal`](https://github.com/localstack/aws-sam-cli-local) wrapper script. +This guide is designed for users new to Serverless Application Repository and assumes basic knowledge of the SAM CLI and our [`lstk sam`](/aws/developer-tools/running-localstack/lstk/) command. Start your LocalStack container using your preferred method, such as via docker-compose. We will demonstrate how to create a SAM application that comprises a Hello World serverless application with a simple API backend using the SAM CLI and then publish it to the Serverless Application Repository by defining it using a SAM template. ### Setup the SAM application -To create a sample SAM application using the `samlocal` CLI, execute the following command: +To create a sample SAM application using the `lstk sam` command, execute the following: ```bash -samlocal init --runtime python3.9 +lstk sam init --runtime python3.9 ``` This command downloads a sample SAM application template and generates a `template.yml` file in the current directory. @@ -35,10 +35,10 @@ The template includes a Lambda function and an API Gateway endpoint that support ### Package the SAM application -Next, we can use the `samlocal` CLI to create a deployment package and a packaged SAM template. +Next, we can use the `lstk sam` command to create a deployment package and a packaged SAM template. Add a Metadata section to your SAM template file (`template.yaml`), and specify the following properties: -To create a deployment package and a packaged SAM template using the `samlocal` CLI, add a Metadata section to your SAM template file (`template.yaml`) and specify the desired properties: +To create a deployment package and a packaged SAM template using the `lstk sam` command, add a Metadata section to your SAM template file (`template.yaml`) and specify the desired properties: ```yaml title="template.yaml" Metadata: @@ -54,7 +54,7 @@ Metadata: Once the Metadata section is added, run the following command to create the Lambda function deployment package and the packaged SAM template: ```bash -samlocal package \ +lstk sam package \ --template-file template.yaml \ --output-template-file packaged.yaml ``` @@ -72,10 +72,10 @@ Resources: ### Retrieve the Application ID -To retrieve the Application ID for your SAM application, you can utilize the [`awslocal`](https://github.com/localstack/awscli-local) CLI by running the following command: +To retrieve the Application ID for your SAM application, you can utilize [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) by running the following command: ```bash -awslocal serverlessrepo list-applications +lstk aws serverlessrepo list-applications ``` In the output, you will observe the `ApplicationId` property in the output, which is the Application ID for your SAM application, along with other properties such as the `Author`, `Description`, `Name`, `SpdxLicenseId`, and `Version` providing further details about your application. @@ -85,7 +85,7 @@ In the output, you will observe the `ApplicationId` property in the output, whic To publish your application to the Serverless Application Repository, execute the following command: ```bash -samlocal publish \ +lstk sam publish \ --template packaged.yaml \ --region us-east-1 ``` @@ -95,7 +95,7 @@ samlocal publish \ To remove a SAM application from the Serverless Application Repository, you can use the following command: ```bash -awslocal serverlessrepo delete-application \ +lstk aws serverlessrepo delete-application \ --application-id ``` diff --git a/src/content/docs/aws/services/servicediscovery.mdx b/src/content/docs/aws/services/servicediscovery.mdx index ed700dbca..a9239265b 100644 --- a/src/content/docs/aws/services/servicediscovery.mdx +++ b/src/content/docs/aws/services/servicediscovery.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting Started -This guide is designed for users new to Service Discovery and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Service Discovery and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create an ECS service containing a Fargate task that uses Service Discovery with the AWS CLI. @@ -30,7 +30,7 @@ This API allows you to define a custom name for your namespace and specify the V To create the private Cloud Map service discovery namespace, execute the following command: ```bash -awslocal servicediscovery create-private-dns-namespace \ +lstk aws servicediscovery create-private-dns-namespace \ --name tutorial \ --vpc ``` @@ -42,7 +42,7 @@ This identifier can be used to check the status of the operation. To verify the status of the operation, execute the following command: ```bash -awslocal servicediscovery get-operation \ +lstk aws servicediscovery get-operation \ --operation-id ``` @@ -56,7 +56,7 @@ This service represents a specific component or resource in your application. To create a service within the namespace, execute the following command: ```bash -awslocal servicediscovery create-service \ +lstk aws servicediscovery create-service \ --name myapplication \ --dns-config "NamespaceId="",DnsRecords=[{Type="A",TTL="300"}]" \ --health-check-custom-config FailureThreshold=1 @@ -73,7 +73,7 @@ Start by creating an ECS cluster using the [`CreateCluster`](https://docs.aws.am Execute the following command: ```bash -awslocal ecs create-cluster \ +lstk aws ecs create-cluster \ --cluster-name tutorial ``` @@ -121,7 +121,7 @@ Register the task definition using the [`RegisterTaskDefinition`](https://docs.a Execute the following command: ```bash -awslocal ecs register-task-definition \ +lstk aws ecs register-task-definition \ --cli-input-json file://fargate-task.json ``` @@ -132,7 +132,7 @@ You can obtain this information by using the [`DescribeVpcs`](https://docs.aws.a Execute the following command to retrieve the details of all VPCs: ```bash -awslocal ec2 describe-vpcs +lstk aws ec2 describe-vpcs ``` The output will include a list of VPCs. @@ -141,12 +141,12 @@ Locate the VPC that was used to create the Cloud Map namespace and make a note o Next, execute the following commands to retrieve the `securityGroups` and `subnets` associated with the VPC: ```bash -awslocal ec2 describe-security-groups \ +lstk aws ec2 describe-security-groups \ --filters Name=vpc-id,Values=vpc- \ --query 'SecurityGroups[*].[GroupId, GroupName]' \ --output text -awslocal ec2 describe-subnets \ +lstk aws ec2 describe-subnets \ --filters Name=vpc-id,Values=vpc- \ --query 'Subnets[*].[SubnetId, CidrBlock]' \ --output text @@ -184,7 +184,7 @@ Create your ECS service using the [`CreateService`](https://docs.aws.amazon.com/ Execute the following command: ```bash -awslocal ecs create-service \ +lstk aws ecs create-service \ --cli-input-json file://ecs-service-discovery.json ``` @@ -194,7 +194,7 @@ You can use the Service Discovery service ID to verify that the service was crea Execute the following command: ```bash -awslocal servicediscovery list-instances \ +lstk aws servicediscovery list-instances \ --service-id ``` @@ -219,10 +219,10 @@ Both conditions and only support a single value to match by. The following examples demonstrate how to use filters with these operations: ```bash -awslocal servicediscovery list-namespaces \ +lstk aws servicediscovery list-namespaces \ --filters "Name=HTTP_NAME,Values=['example-namespace'],Condition=EQ" -awslocal servicediscovery list-services \ +lstk aws servicediscovery list-services \ --filters "Name=NAMESPACE_ID,Values=['id_to_match']" ``` @@ -232,7 +232,7 @@ Conditions in parameters must match return values, while if one ore more conditi This command will only return instances where the parameter `env` is equal to `fuu`: ```bash -awslocal servicediscovery discover-instances \ +lstk aws servicediscovery discover-instances \ --namespace-name example-namespace \ --service-name example-service \ --query-parameters "env"="fuu" @@ -241,7 +241,7 @@ awslocal servicediscovery discover-instances \ This command instead will return all instances where the optional parameter `env` is equal to `bar`, but if no instances match, all instances are returned: ```bash -awslocal servicediscovery discover-instances \ +lstk aws servicediscovery discover-instances \ --namespace-name example-namespace \ --service-name example-service \ --optional-parameters "env"="bar" diff --git a/src/content/docs/aws/services/ses.mdx b/src/content/docs/aws/services/ses.mdx index 9bce3bec9..55bfc2ebe 100644 --- a/src/content/docs/aws/services/ses.mdx +++ b/src/content/docs/aws/services/ses.mdx @@ -21,7 +21,7 @@ For advanced features like SMTP integration and other emulation capabilities, pl ## Getting Started This is an introductory guide to get started with SES. -Basic knowledge of the AWS CLI and LocalStack [`awslocal`](https://github.com/localstack/awscli-local) command is assumed. +Basic knowledge of the AWS CLI and LocalStack [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command is assumed. Start LocalStack using your preferred method. @@ -31,9 +31,9 @@ A verified identity appears as part of the 'From' field in the sent email. A singular email identity can be added using the `VerifyEmailIdentity` operation. ```bash -awslocal ses verify-email-identity --email hello@example.com +lstk aws ses verify-email-identity --email hello@example.com -awslocal ses list-identities +lstk aws ses list-identities ``` ```bash title="Output" @@ -52,7 +52,7 @@ In LocalStack, identities are automatically verified. Next, emails can be sent using the `SendEmail` operation. ```bash -awslocal ses send-email \ +lstk aws ses send-email \ --from "hello@example.com" \ --message 'Body={Text={Data="This is the email body"}},Subject={Data="This is the email subject"}' \ --destination 'ToAddresses=jeff@aws.com' diff --git a/src/content/docs/aws/services/shield.mdx b/src/content/docs/aws/services/shield.mdx index dd783665e..f8520081c 100644 --- a/src/content/docs/aws/services/shield.mdx +++ b/src/content/docs/aws/services/shield.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting Started -This guide is designed for users new to Shield and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Shield and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a Shield protection, list all protections, and delete a protection with the AWS CLI. @@ -28,7 +28,7 @@ To create a Shield protection, use the [`CreateProtection`](https://docs.aws.ama The following command creates a Shield protection for a resource: ```bash -awslocal shield create-protection \ +lstk aws shield create-protection \ --name "my-protection" \ --resource-arn "arn:aws:elasticloadbalancing:us-east-1:000000000000:loadbalancer/app/my-alb/1234567890" ``` @@ -45,7 +45,7 @@ To list all Shield protections, use the [`ListProtections`](https://docs.aws.ama The following command lists all Shield protections: ```bash -awslocal shield list-protections +lstk aws shield list-protections ``` ```bash title="Output" @@ -67,7 +67,7 @@ To describe a Shield protection, use the [`DescribeProtection`](https://docs.aws The following command describes a Shield protection: ```bash -awslocal shield describe-protection \ +lstk aws shield describe-protection \ --protection-id "67908d33-16c0-443d-820a-31c02c4d5976" ``` @@ -90,7 +90,7 @@ To delete a Shield protection, use the [`DeleteProtection`](https://docs.aws.ama The following command deletes a Shield protection: ```bash -awslocal shield delete-protection \ +lstk aws shield delete-protection \ --protection-id "67908d33-16c0-443d-820a-31c02c4d5976" ``` diff --git a/src/content/docs/aws/services/sns.mdx b/src/content/docs/aws/services/sns.mdx index 8307b135c..bf87da7df 100644 --- a/src/content/docs/aws/services/sns.mdx +++ b/src/content/docs/aws/services/sns.mdx @@ -18,7 +18,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started This guide is intended for users who wish to get more acquainted with SNS over LocalStack. -It assumes you have basic knowledge of the AWS CLI (and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script). +It assumes you have basic knowledge of the AWS CLI (and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command). Start your LocalStack container using your preferred method. We will demonstrate how to create an SNS topic, publish messages, and subscribe to the topic. @@ -29,14 +29,14 @@ To create an SNS topic, use the [`CreateTopic`](https://docs.aws.amazon.com/sns/ Run the following command to create a topic named `localstack-topic`: ```bash -awslocal sns create-topic --name localstack-topic +lstk aws sns create-topic --name localstack-topic ``` You can set the SNS topic attribute using the SNS topic you created previously by using the [`SetTopicAttributes`](https://docs.aws.amazon.com/sns/latest/api/API_SetTopicAttributes.html) API. Run the following command to set the `DisplayName` attribute for the topic: ```bash -awslocal sns set-topic-attributes \ +lstk aws sns set-topic-attributes \ --topic-arn arn:aws:sns:us-east-1:000000000000:localstack-topic \ --attribute-name DisplayName \ --attribute-value MyTopicDisplayName @@ -46,7 +46,7 @@ You can list all the SNS topics using the [`ListTopics`](https://docs.aws.amazon Run the following command to list all the SNS topics: ```bash -awslocal sns list-topics +lstk aws sns list-topics ``` ### Get attributes and publish messages to SNS topic @@ -55,7 +55,7 @@ You can get attributes for a single SNS topic using the [`GetTopicAttributes`](h Run the following command to get the attributes for the SNS topic: ```bash -awslocal sns get-topic-attributes \ +lstk aws sns get-topic-attributes \ --topic-arn arn:aws:sns:us-east-1:000000000000:localstack-topic ``` @@ -65,7 +65,7 @@ To publish messages to the SNS topic, create a new file named `messages.txt` in Run the following command to publish messages to the SNS topic using the [`Publish`](https://docs.aws.amazon.com/sns/latest/api/API_Publish.html) API: ```bash -awslocal sns publish \ +lstk aws sns publish \ --topic-arn "arn:aws:sns:us-east-1:000000000000:localstack-topic" \ --message file://message.txt ``` @@ -76,7 +76,7 @@ You can subscribe to the SNS topic using the [`Subscribe`](https://docs.aws.amaz Run the following command to subscribe to the SNS topic: ```bash -awslocal sns subscribe \ +lstk aws sns subscribe \ --topic-arn arn:aws:sns:us-east-1:000000000000:localstack-topic \ --protocol email \ --notification-endpoint test@gmail.com @@ -86,7 +86,7 @@ You can configure the SNS Subscription attributes, using the `SubscriptionArn` r For example, run the following command to set the `RawMessageDelivery` attribute for the subscription: ```bash -awslocal sns set-subscription-attributes \ +lstk aws sns set-subscription-attributes \ --subscription-arn arn:aws:sns:us-east-1:000000000000:test-topic:b6f5e924-dbb3-41c9-aa3b-589dbae0cfff \ --attribute-name RawMessageDelivery --attribute-value true ``` @@ -99,7 +99,7 @@ A Common technology to integrate with is SQS. First we need to ensure we create an SQS queue named `my-queue`: ```bash -awslocal sqs create-queue --queue-name my-queue +lstk aws sqs create-queue --queue-name my-queue ``` ```bash title="Output" @@ -111,7 +111,7 @@ awslocal sqs create-queue --queue-name my-queue Subscribe the SQS queue to the topic we created previously: ```bash -awslocal sns subscribe \ +lstk aws sns subscribe \ --topic-arn "arn:aws:sns:us-east-1:000000000000:localstack-topic" \ --protocol sqs \ --notification-endpoint "arn:aws:sqs:us-east-1:000000000000:my-queue" @@ -126,7 +126,7 @@ awslocal sns subscribe \ Sending a message to the queue, via the topic ```bash -awslocal sns publish --topic-arn "arn:aws:sns:us-east-1:000000000000:localstack-topic" --message "hello" +lstk aws sns publish --topic-arn "arn:aws:sns:us-east-1:000000000000:localstack-topic" --message "hello" { "MessageId": "5a1593ce-411b-44dc-861d-907daa05353b" } @@ -135,7 +135,7 @@ awslocal sns publish --topic-arn "arn:aws:sns:us-east-1:000000000000:localstack- Check that our message has arrived: ```bash -awslocal sqs receive-message \ +lstk aws sqs receive-message \ --queue-url "http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/my-queue" ``` @@ -157,7 +157,7 @@ You can list all the SNS subscriptions using the [`ListSubscriptions`](https://d Run the following command to list all the SNS subscriptions: ```bash -awslocal sns list-subscriptions +lstk aws sns list-subscriptions ``` ```bash title="Output" @@ -177,7 +177,7 @@ awslocal sns list-subscriptions Then, use the ARN to unsubscribe ```bash -awslocal sns unsubscribe \ +lstk aws sns unsubscribe \ --subscription-arn "arn:aws:sns:us-east-1:000000000000:localstack-topic:636e2a73-0dda-4e09-9fdf-77f113d0edd8" ``` @@ -245,7 +245,7 @@ In this example, we will create a platform endpoint in SNS and publish a message Run the following commands to create a platform endpoint: ```bash -awslocal sns create-platform-application \ +lstk aws sns create-platform-application \ --name app-test \ --platform APNS \ --attributes {} @@ -260,7 +260,7 @@ awslocal sns create-platform-application \ Using the `PlatformApplicationArn` from the previous call: ```bash -awslocal sns create-platform-endpoint \ +lstk aws sns create-platform-endpoint \ --platform-application-arn "arn:aws:sns:us-east-1:000000000000:app/APNS/app-test" \ --token my-fake-token ``` @@ -276,7 +276,7 @@ awslocal sns create-platform-endpoint \ Publish a message to the platform endpoint: ```bash -awslocal sns publish \ +lstk aws sns publish \ --target-arn "arn:aws:sns:us-east-1:000000000000:endpoint/APNS/app-test/c25f353e-856b-4b02-a725-6bde35e6e944" \ --message '{"APNS_PLATFORM": "{\"aps\": {\"content-available\": 1}}"}' \ --message-structure json @@ -366,7 +366,7 @@ In this example, we will publish a message to a phone number and retrieve it: Publish a message to a phone number: ```bash -awslocal sns publish \ +lstk aws sns publish \ --phone-number "" \ --message "Hello World!" ``` @@ -457,7 +457,7 @@ In this example, we will subscribe to an external SNS integration not confirming Create an SNS topic, and create a subscription to a external HTTP SNS integration: ```bash -awslocal sns create-topic --name "test-external-integration" +lstk aws sns create-topic --name "test-external-integration" ``` ```bash title="Output" @@ -469,7 +469,7 @@ awslocal sns create-topic --name "test-external-integration" We now create an HTTP SNS subscription to an external endpoint: ```bash -awslocal sns subscribe \ +lstk aws sns subscribe \ --topic-arn "arn:aws:sns:us-east-1:000000000000:test-external-integration" \ --protocol https \ --notification-endpoint "https://api.opsgenie.com/v1/json/amazonsns?apiKey=b13fd59a-9" \ @@ -486,7 +486,7 @@ Now, we can check the `PendingConfirmation` status of our subscription, showing You will need to use the `SubscriptionArn` from the response of your subscribe call: ```bash -awslocal sns get-subscription-attributes \ +lstk aws sns get-subscription-attributes \ --subscription-arn "arn:aws:sns:us-east-1:000000000000:test-external-integration:c3ab47f3-b964-461d-84eb-903d8765b0c8" ``` @@ -523,7 +523,7 @@ curl "http://localhost:4566/_aws/sns/subscription-tokens/arn:aws:sns:us-east-1:0 We can now use this token to manually confirm the subscription: ```bash -awslocal sns confirm-subscription \ +lstk aws sns confirm-subscription \ --topic-arn "arn:aws:sns:us-east-1:000000000000:test-external-integration" \ --token 75732d656173742d312f3b875fb03b875fb03b875fb03b875fb03b875fb03b87 ``` @@ -537,7 +537,7 @@ awslocal sns confirm-subscription \ We can now finally verify the subscription has been confirmed: ```bash -awslocal sns get-subscription-attributes \ +lstk aws sns get-subscription-attributes \ --subscription-arn "arn:aws:sns:us-east-1:000000000000:test-external-integration:c3ab47f3-b964-461d-84eb-903d8765b0c8" ``` diff --git a/src/content/docs/aws/services/sqs.mdx b/src/content/docs/aws/services/sqs.mdx index d8e4babd2..ee2050eaf 100644 --- a/src/content/docs/aws/services/sqs.mdx +++ b/src/content/docs/aws/services/sqs.mdx @@ -18,7 +18,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to SQS and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to SQS and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create an SQS queue, retrieve queue attributes and URLs, and receive and delete messages from the queue. @@ -29,14 +29,14 @@ To create an SQS queue, use the [`CreateQueue`](https://docs.aws.amazon.com/AWSS Run the following command to create a queue named `localstack-queue`: ```bash -awslocal sqs create-queue --queue-name localstack-queue +lstk aws sqs create-queue --queue-name localstack-queue ``` You can list all queues in your account using the [`ListQueues`](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ListQueues.html) API. Run the following command to list all queues in your account: ```bash -awslocal sqs list-queues +lstk aws sqs list-queues ``` ```bash title="Output" @@ -53,7 +53,7 @@ You need to pass the `queue-url` and `attribute-names` parameters. Run the following command to retrieve the queue attributes: ```bash -awslocal sqs get-queue-attributes \ +lstk aws sqs get-queue-attributes \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/localstack-queue \ --attribute-names All ``` @@ -61,7 +61,7 @@ awslocal sqs get-queue-attributes \ To create a [FIFO queue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-fifo-queue-message-identifiers.html), the queue name must end with the `.fifo` suffix in addition to the `FifoQueue=true` attribute set: ```bash -awslocal sqs create-queue --queue-name localstack-queue.fifo --attributes "FifoQueue=true" +lstk aws sqs create-queue --queue-name localstack-queue.fifo --attributes "FifoQueue=true" { "QueueUrl": "http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/localstack-queue.fifo" } @@ -75,7 +75,7 @@ To send a message to a SQS queue, you can use the [`SendMessage`](https://docs.a Run the following command to send a message to the queue: ```bash -awslocal sqs send-message \ +lstk aws sqs send-message \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/localstack-queue \ --message-body "Hello World" ``` @@ -93,7 +93,7 @@ You can receive messages from the queue using the [`ReceiveMessage`](https://doc Run the following command to receive messages from the queue: ```bash -awslocal sqs receive-message \ +lstk aws sqs receive-message \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/localstack-queue ``` @@ -107,7 +107,7 @@ You need to pass the `queue-url` and `receipt-handle` parameters. Run the following command to delete a message from the queue: ```bash -awslocal sqs delete-message \ +lstk aws sqs delete-message \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/localstack-queue \ --receipt-handle ``` @@ -118,7 +118,7 @@ If you have sent multiple messages to the queue, you can purge the queue using t Run the following command to purge the queue: ```bash -awslocal sqs purge-queue \ +lstk aws sqs purge-queue \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/localstack-queue ``` @@ -131,9 +131,9 @@ First, create three queues. One will serve as original input queue, one as DLQ, and the third as target for DLQ redrive. ```bash -awslocal sqs create-queue --queue-name input-queue -awslocal sqs create-queue --queue-name dead-letter-queue -awslocal sqs create-queue --queue-name recovery-queue +lstk aws sqs create-queue --queue-name input-queue +lstk aws sqs create-queue --queue-name dead-letter-queue +lstk aws sqs create-queue --queue-name recovery-queue ``` ```bash title="Output" @@ -151,7 +151,7 @@ awslocal sqs create-queue --queue-name recovery-queue Configure `dead-letter-queue` to be a DLQ for `input-queue`: ```bash -awslocal sqs set-queue-attributes \ +lstk aws sqs set-queue-attributes \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/input-queue \ --attributes '{ "RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-east-1:000000000000:dead-letter-queue\",\"maxReceiveCount\":\"1\"}" @@ -161,7 +161,7 @@ awslocal sqs set-queue-attributes \ Send a message to the input queue: ```bash -awslocal sqs send-message \ +lstk aws sqs send-message \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/input-queue \ --message-body '{"hello": "world"}' ``` @@ -169,10 +169,10 @@ awslocal sqs send-message \ Receive the message twice to provoke a move into the dead-letter queue: ```bash -awslocal sqs receive-message \ +lstk aws sqs receive-message \ --visibility-timeout 0 \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/input-queue -awslocal sqs receive-message \ +lstk aws sqs receive-message \ --visibility-timeout 0 \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/input-queue ``` @@ -186,7 +186,7 @@ In the localstack logs you should see something like the following line, indicat Now, start a message move task to asynchronously move the messages from the DLQ into the recovery queue: ```bash -awslocal sqs start-message-move-task \ +lstk aws sqs start-message-move-task \ --source-arn arn:aws:sqs:us-east-1:000000000000:dead-letter-queue \ --destination-arn arn:aws:sqs:us-east-1:000000000000:recovery-queue ``` @@ -194,7 +194,7 @@ awslocal sqs start-message-move-task \ Listing the message move tasks should yield something like ```bash -awslocal sqs list-message-move-tasks \ +lstk aws sqs list-message-move-tasks \ --source-arn arn:aws:sqs:us-east-1:000000000000:dead-letter-queue ``` @@ -216,7 +216,7 @@ awslocal sqs list-message-move-tasks \ Receiving messages from the recovery queue should now show us the original message: ```bash -awslocal sqs receive-message \ +lstk aws sqs receive-message \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/recovery-queue ``` diff --git a/src/content/docs/aws/services/ssm.mdx b/src/content/docs/aws/services/ssm.mdx index bf11f9700..b01ebf66f 100644 --- a/src/content/docs/aws/services/ssm.mdx +++ b/src/content/docs/aws/services/ssm.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Systems Manager (SSM) and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Systems Manager (SSM) and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method with an additional `EC2_VM_MANAGER=docker` configuration variable. We will demonstrate how to use EC2 and SSM functionalities when using the Docker backend with LocalStack with the AWS CLI. @@ -39,7 +39,7 @@ You can run an EC2 instance using the [`RunInstances`](https://docs.aws.amazon.c Execute the following command to create an EC2 instance using the `ami-00a001` AMI. ```bash -awslocal ec2 run-instances \ +lstk aws ec2 run-instances \ --image-id ami-00a001 --count 1 ``` @@ -71,7 +71,7 @@ You can use the [`SendCommand`](https://docs.aws.amazon.com/systems-manager/late The following command sends a `cat lsb-release` command in the `/etc` directory to the EC2 instance. ```bash -awslocal ssm send-command --document-name "AWS-RunShellScript" \ +lstk aws ssm send-command --document-name "AWS-RunShellScript" \ --document-version "1" \ --instance-ids i-abf6920789a06dd84 \ --parameters "commands='cat lsb-release',workingDirectory=/etc" @@ -99,7 +99,7 @@ You can use the [`GetCommandInvocation`](https://docs.aws.amazon.com/systems-man The following command retrieves the output of the command sent in the previous step. ```bash -awslocal ssm get-command-invocation \ +lstk aws ssm get-command-invocation \ --command-id 23547a9b-6993-4967-9446-f96b9b5dac70 \ --instance-id i-abf6920789a06dd84 ``` diff --git a/src/content/docs/aws/services/sso-admin.mdx b/src/content/docs/aws/services/sso-admin.mdx index 4704a90cb..e129ce9bd 100644 --- a/src/content/docs/aws/services/sso-admin.mdx +++ b/src/content/docs/aws/services/sso-admin.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to SSO Admin and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to SSO Admin and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a permission set, add tags to a permission set, and list permission sets. @@ -27,7 +27,7 @@ We will demonstrate how to create a permission set, add tags to a permission set You can create a permission set using the [`CreatePermissionSet`](https://docs.aws.amazon.com/sso-admin/latest/APIReference/API_CreatePermissionSet.html) API. ```bash -awslocal sso-admin create-permission-set \ +lstk aws sso-admin create-permission-set \ --name my-permission-set \ --description "My permission set" \ --instance-arn arn:aws:sso:::instance/d-1234567890 \ @@ -51,7 +51,7 @@ awslocal sso-admin create-permission-set \ You can list permission sets using the [`ListPermissionSets`](https://docs.aws.amazon.com/sso-admin/latest/APIReference/API_ListPermissionSets.html) API. ```bash -awslocal sso-admin list-permission-sets --instance-arn arn:aws:sso:::instance/d-1234567890 +lstk aws sso-admin list-permission-sets --instance-arn arn:aws:sso:::instance/d-1234567890 ``` ```bash title="Output" @@ -67,7 +67,7 @@ awslocal sso-admin list-permission-sets --instance-arn arn:aws:sso:::instance/d- You can list tags for a permission set using the [`ListTagsForResource`](https://docs.aws.amazon.com/sso-admin/latest/APIReference/API_ListTagsForResource.html) API. ```bash -awslocal sso-admin list-tags-for-resource --resource-arn arn:aws:sso:::instance/d-1234567890/ps-lm0rshcjz3tikab8 --instance-arn arn:aws:sso:::instance/d-1234567890 +lstk aws sso-admin list-tags-for-resource --resource-arn arn:aws:sso:::instance/d-1234567890/ps-lm0rshcjz3tikab8 --instance-arn arn:aws:sso:::instance/d-1234567890 ``` ```bash title="Output" diff --git a/src/content/docs/aws/services/stepfunctions.mdx b/src/content/docs/aws/services/stepfunctions.mdx index 7a96eecc5..b7a7b7ee2 100644 --- a/src/content/docs/aws/services/stepfunctions.mdx +++ b/src/content/docs/aws/services/stepfunctions.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Step Functions and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Step Functions and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how you can create a state machine, execute it, and check the status of the execution. @@ -29,7 +29,7 @@ The API requires the name of the state machine, the state machine definition, an Run the following command to create a state machine: ```bash showLineNumbers -awslocal stepfunctions create-state-machine \ +lstk aws stepfunctions create-state-machine \ --name "CreateAndListBuckets" \ --definition '{ "Comment": "Create bucket and list buckets", @@ -67,7 +67,7 @@ The API requires the state machine's ARN and the state machine's input. Run the following command to execute the state machine: ```bash -awslocal stepfunctions start-execution \ +lstk aws stepfunctions start-execution \ --state-machine-arn "arn:aws:states:us-east-1:000000000000:stateMachine:CreateAndListBuckets" ``` @@ -84,7 +84,7 @@ To check the status of the execution, you can use the [`DescribeExecution`](http Run the following command to describe the execution: ```bash -awslocal stepfunctions describe-execution \ +lstk aws stepfunctions describe-execution \ --execution-arn "arn:aws:states:us-east-1:000000000000:execution:CreateAndListBuckets:bf7d2138-e96f-42d1-b1f9-41f0c1c7bc3e" ``` @@ -387,10 +387,19 @@ If you're running LocalStack in Docker, mount the file and pass the variable as import { Tabs, TabItem } from '@astrojs/starlight/components'; - + +Add the mount to your `config.toml`: + +```toml +[[containers]] +type = "aws" +volumes = ["/path/to/MockConfigFile.json:/tmp/MockConfigFile.json"] +``` + +Then set the environment variable and start LocalStack: + ```bash -LOCALSTACK_SFN_MOCK_CONFIG=/tmp/MockConfigFile.json \ -localstack start --volume /path/to/MockConfigFile.json:/tmp/MockConfigFile.json +LOCALSTACK_SFN_MOCK_CONFIG=/tmp/MockConfigFile.json lstk start ``` @@ -421,7 +430,7 @@ Create the state machine to match the name defined in the mock configuration fil In this example, create the `LambdaSQSIntegration` state machine using: ```bash -awslocal stepfunctions create-state-machine \ +lstk aws stepfunctions create-state-machine \ --definition file://LambdaSQSIntegration.json \ --name "LambdaSQSIntegration" \ --role-arn "arn:aws:iam::000000000000:role/service-role/testrole" @@ -436,7 +445,7 @@ This tells LocalStack to apply the corresponding mocked responses from the confi For example, to run the `BaseCase` test case: ```bash -awslocal stepfunctions start-execution \ +lstk aws stepfunctions start-execution \ --state-machine arn:aws:states:us-east-1:000000000000:stateMachine:LambdaSQSIntegration#BaseCase \ --input '{"name": "John", "surname": "smith"}' \ --name "MockExecutionBaseCase" @@ -448,7 +457,7 @@ States without mock entries invoke the actual emulated service as usual. You can inspect the execution using the [`DescribeExecution`](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeExecution.html) API: ```bash -awslocal stepfunctions describe-execution \ +lstk aws stepfunctions describe-execution \ --execution-arn "arn:aws:states:us-east-1:000000000000:execution:LambdaSQSIntegration:MockExecutionBaseCase" ``` @@ -474,7 +483,7 @@ awslocal stepfunctions describe-execution \ You can also use the [`GetExecutionHistory`](https://docs.aws.amazon.com/step-functions/latest/apireference/API_GetExecutionHistory.html) API to retrieve the execution history, including the events and their details. ```bash -awslocal stepfunctions get-execution-history \ +lstk aws stepfunctions get-execution-history \ --execution-arn "arn:aws:states:us-east-1:000000000000:execution:LambdaSQSIntegration:MockExecutionBaseCase" ``` diff --git a/src/content/docs/aws/services/sts.mdx b/src/content/docs/aws/services/sts.mdx index d01c03f5b..52d1cf65e 100644 --- a/src/content/docs/aws/services/sts.mdx +++ b/src/content/docs/aws/services/sts.mdx @@ -18,7 +18,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to STS and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to STS and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to assume an IAM Role and assume the role as well as creating an IAM user and getting using the STS with the AWS CLI. @@ -30,7 +30,7 @@ The IAM User will be used to assume the IAM Role. Run the following command to create an IAM User, named `localstack-user`: ```bash -awslocal iam create-user \ +lstk aws iam create-user \ --user-name localstack-user ``` @@ -38,7 +38,7 @@ You can generate long-term access keys for the IAM user using the [`CreateAccess Run the following command to create an access key for the IAM user: ```bash -awslocal iam create-access-key \ +lstk aws iam create-access-key \ --user-name localstack-user ``` @@ -58,7 +58,7 @@ Using STS, you can also fetch temporary credentials for this user using the [`Ge Run the following command using your long-term credentials to get your temporary credentials: ```bash -awslocal sts get-session-token +lstk aws sts get-session-token ``` ```bash title="Output" @@ -78,7 +78,7 @@ You can now create an IAM Role, named `localstack-role`, using the [`CreateRole` Run the following command to create the IAM Role: ```bash -awslocal iam create-role \ +lstk aws iam create-role \ --role-name localstack-role \ --assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"AWS":"arn:aws:iam::000000000000:root"},"Action":"sts:AssumeRole"}]}' ``` @@ -111,7 +111,7 @@ You can attach the policy to the IAM role using the [`AttachRolePolicy`](https:/ Run the following command to attach the policy to the IAM role: ```bash -awslocal iam attach-role-policy \ +lstk aws iam attach-role-policy \ --role-name localstack-role \ --policy-arn arn:aws:iam::aws:policy/AdministratorAccess ``` @@ -122,7 +122,7 @@ You can assume an IAM Role using the [`AssumeRole`](https://docs.aws.amazon.com/ Run the following command to assume the IAM Role: ```bash -awslocal sts assume-role \ +lstk aws sts assume-role \ --role-arn arn:aws:iam::000000000000:role/localstack-role \ --role-session-name localstack-session ``` @@ -151,7 +151,7 @@ You can get the caller identity to identify the principal your current credentia Run the following command to get the caller identity for the credentials set in your environment: ```bash -awslocal sts get-caller-identity +lstk aws sts get-caller-identity ``` ```bash title="Output" diff --git a/src/content/docs/aws/services/support.mdx b/src/content/docs/aws/services/support.mdx index 19ba8b7b8..dfc9bf7cd 100644 --- a/src/content/docs/aws/services/support.mdx +++ b/src/content/docs/aws/services/support.mdx @@ -24,7 +24,7 @@ It's important to note that LocalStack doesn't offer a programmatic interface to ## Getting started -This guide is designed for users new to Support and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Support and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how you can create a case in the mock Support Center using the AWS CLI. @@ -35,7 +35,7 @@ To create a support case, you can use the [`CreateCase`](https://docs.aws.amazon The following example creates a case with the subject "Test case" and the description "This is a test case" in the category "General guidance". ```bash -awslocal support create-case \ +lstk aws support create-case \ --subject "Test case" \ --service-code "general-guidance" \ --category-code "general-guidance" \ @@ -54,7 +54,7 @@ To list all support cases, you can use the [`DescribeCases`](https://docs.aws.am The following example lists all cases in the category "General guidance". ```bash -awslocal support describe-cases +lstk aws support describe-cases ``` ```bash title="Output" @@ -87,7 +87,7 @@ To resolve a support case, you can use the [`ResolveCase`](https://docs.aws.amaz The following example resolves the case created in the previous step. ```bash -awslocal support resolve-case \ +lstk aws support resolve-case \ --case-id "case-12345678910-2020-kEa16f90bJE766J4" ``` diff --git a/src/content/docs/aws/services/swf.mdx b/src/content/docs/aws/services/swf.mdx index adfe279af..d0c5f8ce7 100644 --- a/src/content/docs/aws/services/swf.mdx +++ b/src/content/docs/aws/services/swf.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Simple Workflow Service and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Simple Workflow Service and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to register an SWF domain and workflow using the AWS CLI. @@ -28,7 +28,7 @@ You can register an SWF domain using the [`RegisterDomain`](https://docs.aws.ama Execute the following command to register a domain named `test-domain`: ```bash -awslocal swf register-domain \ +lstk aws swf register-domain \ --name test-domain \ --workflow-execution-retention-period-in-days 1 ``` @@ -37,7 +37,7 @@ You can use the [`DescribeDomain`](https://docs.aws.amazon.com/amazonswf/latest/ Run the following command to describe the `test-domain` domain: ```bash -awslocal swf describe-domain \ +lstk aws swf describe-domain \ --name test-domain ``` @@ -60,21 +60,21 @@ You can list all registered domains using the [`ListDomains`](https://docs.aws.a Run the following command to list all registered domains: ```bash -awslocal swf list-domains --registration-status REGISTERED +lstk aws swf list-domains --registration-status REGISTERED ``` To deprecate a domain, use the [`DeprecateDomain`](https://docs.aws.amazon.com/amazonswf/latest/apireference/API_DeprecateDomain.html) API. Run the following command to deprecate the `test-domain` domain: ```bash -awslocal swf deprecate-domain \ +lstk aws swf deprecate-domain \ --name test-domain ``` You can now list the deprecated domains using the `--registration-status DEPRECATED` flag: ```bash -awslocal swf list-domains --registration-status DEPRECATED +lstk aws swf list-domains --registration-status DEPRECATED ``` ### Registering a workflow @@ -83,7 +83,7 @@ You can register a workflow using the [`RegisterWorkflowType`](https://docs.aws. Execute the following command to register a workflow named `test-workflow`: ```bash showLineNumbers -awslocal swf register-workflow-type \ +lstk aws swf register-workflow-type \ --domain test-domain \ --name test-workflow \ --default-task-list name=test-task-list \ @@ -97,7 +97,7 @@ You can use the [`DescribeWorkflowType`](https://docs.aws.amazon.com/amazonswf/l Run the following command to describe the `test-workflow` workflow: ```bash -awslocal swf describe-workflow-type \ +lstk aws swf describe-workflow-type \ --domain test-domain \ --workflow-type name=test-workflow,version=1.0 ``` @@ -131,7 +131,7 @@ You can register an activity using the [`RegisterActivityType`](https://docs.aws Execute the following command to register an activity named `test-activity`: ```bash showLineNumbers -awslocal swf register-activity-type \ +lstk aws swf register-activity-type \ --domain test-domain \ --name test-activity \ --default-task-list name=test-task-list \ @@ -146,7 +146,7 @@ You can use the [`DescribeActivityType`](https://docs.aws.amazon.com/amazonswf/l Run the following command to describe the `test-activity` activity: ```bash showLineNumbers -awslocal swf describe-activity-type \ +lstk aws swf describe-activity-type \ --domain test-domain \ --activity-type name=test-activity,version=1.0 ``` @@ -181,7 +181,7 @@ You can start a workflow execution using the [`StartWorkflowExecution`](https:// Execute the following command to start a workflow execution for the `test-workflow` workflow: ```bash showLineNumbers -awslocal swf start-workflow-execution \ +lstk aws swf start-workflow-execution \ --domain test-domain \ --workflow-type name=test-workflow,version=1.0 \ --workflow-id test-workflow-id \ diff --git a/src/content/docs/aws/services/textract.mdx b/src/content/docs/aws/services/textract.mdx index 1181f9c2e..2fd6f7284 100644 --- a/src/content/docs/aws/services/textract.mdx +++ b/src/content/docs/aws/services/textract.mdx @@ -15,7 +15,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), p ## Getting started -This guide is tailored for users new to Textract and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is tailored for users new to Textract and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to perform basic Textract operations, such as mocking text detection in a document. @@ -26,7 +26,7 @@ You can use the [`DetectDocumentText`](https://docs.aws.amazon.com/textract/late Execute the following command: ```bash -awslocal textract detect-document-text \ +lstk aws textract detect-document-text \ --document '{"S3Object":{"Bucket":"your-bucket","Name":"your-document"}}' ``` @@ -48,7 +48,7 @@ You can use the [`StartDocumentTextDetection`](https://docs.aws.amazon.com/textr Execute the following command: ```bash -awslocal textract start-document-text-detection \ +lstk aws textract start-document-text-detection \ --document-location '{"S3Object":{"Bucket":"bucket","Name":"document"}}' ``` @@ -66,7 +66,7 @@ You can use the [`GetDocumentTextDetection`](https://docs.aws.amazon.com/textrac Execute the following command: ```bash -awslocal textract get-document-text-detection \ +lstk aws textract get-document-text-detection \ --job-id "501d7251-1249-41e0-a0b3-898064bfc506" ``` diff --git a/src/content/docs/aws/services/timestream-query.mdx b/src/content/docs/aws/services/timestream-query.mdx index a849ce8fe..dac86c400 100644 --- a/src/content/docs/aws/services/timestream-query.mdx +++ b/src/content/docs/aws/services/timestream-query.mdx @@ -20,27 +20,27 @@ The supported APIs are available on our API Coverage Page ([Timestream Query](#a ## Getting Started -The following example illustrates the basic operations, using the [`awslocal`](https://github.com/localstack/awscli-local) command line. +The following example illustrates the basic operations, using the [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command line. First, we create a test database and table: ```bash -awslocal timestream-write create-database --database-name testDB -awslocal timestream-write create-table --database-name testDB --table-name testTable +lstk aws timestream-write create-database --database-name testDB +lstk aws timestream-write create-table --database-name testDB --table-name testTable ``` We can then add a few records with a timestamp, measure name, and value to the table: ```bash -awslocal timestream-write write-records --database-name testDB --table-name testTable --records '[{"MeasureName":"cpu","MeasureValue":"60","TimeUnit":"SECONDS","Time":"1636986409"}]' -awslocal timestream-write write-records --database-name testDB --table-name testTable --records '[{"MeasureName":"cpu","MeasureValue":"80","TimeUnit":"SECONDS","Time":"1636986412"}]' -awslocal timestream-write write-records --database-name testDB --table-name testTable --records '[{"MeasureName":"cpu","MeasureValue":"70","TimeUnit":"SECONDS","Time":"1636986414"}]' +lstk aws timestream-write write-records --database-name testDB --table-name testTable --records '[{"MeasureName":"cpu","MeasureValue":"60","TimeUnit":"SECONDS","Time":"1636986409"}]' +lstk aws timestream-write write-records --database-name testDB --table-name testTable --records '[{"MeasureName":"cpu","MeasureValue":"80","TimeUnit":"SECONDS","Time":"1636986412"}]' +lstk aws timestream-write write-records --database-name testDB --table-name testTable --records '[{"MeasureName":"cpu","MeasureValue":"70","TimeUnit":"SECONDS","Time":"1636986414"}]' ``` Finally, we can run a query to retrieve the timeseries data (or aggregate values) from the table: ```bash -awslocal timestream-query query --query-string "SELECT CREATE_TIME_SERIES(time, measure_value::double) as cpu FROM testDB.timeStreamTable WHERE measure_name='cpu'" +lstk aws timestream-query query --query-string "SELECT CREATE_TIME_SERIES(time, measure_value::double) as cpu FROM testDB.timeStreamTable WHERE measure_name='cpu'" ``` ```bash title="Output" diff --git a/src/content/docs/aws/services/transcribe.mdx b/src/content/docs/aws/services/transcribe.mdx index 02d02a1f4..0da909d6e 100644 --- a/src/content/docs/aws/services/transcribe.mdx +++ b/src/content/docs/aws/services/transcribe.mdx @@ -22,7 +22,7 @@ Language models typically have a size of around 50 MiB and are saved in the cach ## Getting Started -This guide is designed for users new to Transcribe and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Transcribe and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a transcription job and view the transcript in an S3 bucket using the AWS CLI. @@ -33,8 +33,8 @@ You can create an S3 bucket using the [`mb`](https://docs.aws.amazon.com/cli/lat Run the following command to create a bucket named `foo` to upload a sample audio file named `example.wav`: ```bash -awslocal s3 mb s3://foo -awslocal s3 cp ~/example.wav s3://foo/example.wav +lstk aws s3 mb s3://foo +lstk aws s3 cp ~/example.wav s3://foo/example.wav ``` ### Create a transcription job @@ -43,7 +43,7 @@ You can create a transcription job using the [`StartTranscriptionJob`](https://d Run the following command to create a transcription job named `example` for the audio file `example.wav`: ```bash -awslocal transcribe start-transcription-job \ +lstk aws transcribe start-transcription-job \ --transcription-job-name example \ --media MediaFileUri=s3://foo/example.wav \ --language-code en-IN @@ -53,7 +53,7 @@ You can list the transcription jobs using the [`ListTranscriptionJobs`](https:// Run the following command to list the transcription jobs: ```bash -awslocal transcribe list-transcription-jobs +lstk aws transcribe list-transcription-jobs ``` The following output would be retrieved: @@ -78,7 +78,7 @@ After the job is complete, the transcript can be retrieved from the S3 bucket us Run the following command to get the transcript: ```bash -awslocal transcribe get-transcription-job --transcription-job example +lstk aws transcribe get-transcription-job --transcription-job example ``` ```bash title="Output" @@ -104,7 +104,7 @@ awslocal transcribe get-transcription-job --transcription-job example You can then view the transcript by running the following command: ```bash -awslocal s3 cp s3://foo/7844aaa5.json . +lstk aws s3 cp s3://foo/7844aaa5.json . jq .results.transcripts[0].transcript 7844aaa5.json ``` diff --git a/src/content/docs/aws/services/verifiedpermissions.mdx b/src/content/docs/aws/services/verifiedpermissions.mdx index bca27101d..9088ab7b7 100644 --- a/src/content/docs/aws/services/verifiedpermissions.mdx +++ b/src/content/docs/aws/services/verifiedpermissions.mdx @@ -17,7 +17,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is designed for users new to Verified Permissions and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to Verified Permissions and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how to create a Verified Permissions Policy Store, add a policy to it, and authorize a request with the AWS CLI. @@ -28,7 +28,7 @@ To create a Verified Permissions Policy Store, use the [`CreatePolicyStore`](htt Run the following command to create a Policy Store with Schema validation settings set to `OFF`: ```bash -awslocal verifiedpermissions create-policy-store \ +lstk aws verifiedpermissions create-policy-store \ --validation-settings mode=OFF \ --description "A local Policy Store" ``` @@ -46,7 +46,7 @@ You can list all the Verified Permissions policy stores using the [`ListPolicySt Run the following command to list all the Verified Permissions policy stores: ```bash -awslocal verifiedpermissions list-policy-stores +lstk aws verifiedpermissions list-policy-stores ``` ### Create a Policy @@ -67,7 +67,7 @@ Create a JSON file named `static_policy.json` with the following content: You can then run this command to create the policy: ```bash -awslocal verifiedpermissions create-policy \ +lstk aws verifiedpermissions create-policy \ --definition file://static_policy.json \ --policy-store-id q5PCScu9qo4aswMVc0owNN ``` @@ -107,7 +107,7 @@ We can now make use of the Policy Store and the Policy to start authorizing requ To authorize a request using Verified Permissions, use the [`IsAuthorized`](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorized.html) API. ```bash title="Output" -awslocal verifiedpermissions is-authorized \ +lstk aws verifiedpermissions is-authorized \ --policy-store-id q5PCScu9qo4aswMVc0owNN \ --principal entityType=User,entityId=alice \ --action actionType=Action,actionId=view \ diff --git a/src/content/docs/aws/services/waf.mdx b/src/content/docs/aws/services/waf.mdx index 1d9356844..d3450311e 100644 --- a/src/content/docs/aws/services/waf.mdx +++ b/src/content/docs/aws/services/waf.mdx @@ -16,7 +16,7 @@ The supported APIs are available on our [API Coverage section](#api-coverage), w ## Getting started -This guide is for users who are familiar with the AWS CLI and [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is for users who are familiar with the AWS CLI and [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will walk you through creating, listing, tagging, and viewing tags for Web Access Control Lists (WebACLs) using the Web Application Firewall (WAF) service in a LocalStack environment using the AWS CLI. @@ -27,7 +27,7 @@ Start by creating a Web Access Control List (WebACL) using the [`CreateWebACL`]( Run the following command to create a WebACL named `TestWebAcl`: ```bash showLineNumbers -awslocal wafv2 create-web-acl \ +lstk aws wafv2 create-web-acl \ --name TestWebAcl \ --scope REGIONAL \ --default-action Allow={} \ @@ -53,7 +53,7 @@ To view all the WebACLs you have created, use the [`ListWebACLs`](https://docs.a Run the following command to list the WebACLs: ```bash -awslocal wafv2 list-web-acls --scope REGIONAL +lstk aws wafv2 list-web-acls --scope REGIONAL ``` ```bash title="Output" @@ -77,7 +77,7 @@ Use the [`TagResource`](https://docs.aws.amazon.com/waf/latest/APIReference/API_ Run the following command to add a tag to the WebACL created in the previous step: ```bash -awslocal wafv2 tag-resource \ +lstk aws wafv2 tag-resource \ --resource-arn arn:aws:wafv2:us-east-1:000000000000:regional/webacl/TestWebAcl/f94fd5bc-e4d4-4280-9f53-51e9441ad51d \ --tags Key=Name,Value=AWSWAF ``` @@ -87,7 +87,7 @@ Use the [`ListTagsForResource`](https://docs.aws.amazon.com/waf/latest/APIRefere Run the following command to list the tags for the WebACL created in the previous step: ```bash -awslocal wafv2 list-tags-for-resource \ +lstk aws wafv2 list-tags-for-resource \ --resource-arn arn:aws:wafv2:us-east-1:000000000000:regional/webacl/TestWebAcl/f94fd5bc-e4d4-4280-9f53-51e9441ad51d ``` diff --git a/src/content/docs/aws/services/xray.mdx b/src/content/docs/aws/services/xray.mdx index ac524d896..4313bb83e 100644 --- a/src/content/docs/aws/services/xray.mdx +++ b/src/content/docs/aws/services/xray.mdx @@ -28,7 +28,7 @@ which provides information on the extent of X-Ray integration with LocalStack. ## Getting started This guide is designed for users new to X-Ray and assumes basic -knowledge of the AWS CLI and our `awslocal` wrapper script. +knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/#aws) command. Start your LocalStack container using your preferred method. We will demonstrate how you can create a minimal [trace segment](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html#api-segmentdocuments-fields) @@ -54,7 +54,7 @@ DOC=$(cat < docker compose up ``` +Given that you've started LocalStack via `docker-compose`, you'll need to configure the `lstk` CLI to contact your container: + +```bash +export LSTK_ENDPOINT_URL=http://localhost.localstack.cloud:4566 +``` + ### The Terraform Configuration File The entire Terraform configuration file for setting up the application stack is available in the same repository at @@ -81,12 +87,12 @@ navigate to the project's root folder and use the following commands: ```bash cd terraform -tflocal init -tflocal plan -tflocal apply --auto-approve +lstk terraform init +lstk terraform plan +lstk terraform apply --auto-approve ``` -`tflocal` is a small wrapper script to run Terraform against LocalStack. +`lstk terraform` runs Terraform against LocalStack, using LocalStack endpoints as AWS provider overrides. The endpoints for all services are configured to point to the LocalStack API, which allows you to deploy your unmodified Terraform scripts against LocalStack. @@ -132,7 +138,7 @@ The Terraform configuration file outputs the REST API ID of the API Gateway. We can capture that value and use it further to invoke the **`add-product`** Lambda: ```bash -export rest_api_id=$(cd terraform; tflocal output --raw rest_api_id) +export rest_api_id=$(cd terraform; lstk terraform output --raw rest_api_id) ``` The endpoint for the API Gateway is constructed similarly to the one on AWS: @@ -186,10 +192,10 @@ The Lambda code and the configurations look fine to him. ### Creating a Cloud Pod -To share this exact environment and issue with Alice, a more experienced colleague, Bob only needs to run a simple `localstack pod` command: +To share this exact environment and issue with Alice, a more experienced colleague, Bob only needs to run a simple `lstk snapshot save` command: ```bash -localstack pod save cloud-pod-product-app +lstk snapshot save pod:cloud-pod-product-app ``` ```bash title="Output" @@ -201,31 +207,16 @@ Services: sts,iam,apigateway,dynamodb,lambda,s3,cloudwatch,logs LocalStack provides a remote storage backend that can be used to store the state of your application and share it with your team members. -The Cloud Pods CLI is included in the LocalStack CLI installation, so there's no need for additional plugins to begin using it. +Cloud Pods are managed through the `snapshot` command, included in the `lstk` CLI installation, so there's no need for additional plugins to begin using it. The `LOCALSTACK_AUTH_TOKEN` needs to be set as an environment variable. -Additionally, there are other commands for managing Cloud Pods included in the CLI: - -```bash -localstack pod --help -``` - -```bash title="Output" -Usage: localstack pod [OPTIONS] COMMAND [ARGS]... - - Manage the state of your instance via Cloud Pods. - -Options: - -h, --help Show this message and exit. +Additionally, there are other `snapshot` subcommands for managing Cloud Pods: -Commands: - delete Delete a Cloud Pod - list List all available Cloud Pods - load Load the state of a Cloud Pod into the application runtime - remote Manage Cloud Pod remotes - save Create a new Cloud Pod - versions List all available versions for a Cloud Pod -``` +- `lstk snapshot save` (alias `lstk save`) — create a new Cloud Pod +- `lstk snapshot load` (alias `lstk load`) — load the state of a Cloud Pod into the application runtime +- `lstk snapshot list` — list all available Cloud Pods +- `lstk snapshot remove` — delete a Cloud Pod +- `lstk snapshot show` — show metadata for a Cloud Pod ### Pulling and Loading the Cloud Pod @@ -237,7 +228,7 @@ Now, in a fresh LocalStack instance, Alice can immediately load the Cloud Pod, b same organization: ```bash -localstack pod load cloud-pod-product-app +lstk snapshot load pod:cloud-pod-product-app ``` ```bash title="Output" @@ -329,11 +320,11 @@ start to finish. ### Other Remote Options -For organizations with specific data regulations, LocalStack offers multiple remote storage options for Cloud Pods, +For organizations with specific data regulations, LocalStack offers an Amazon S3 storage option, allowing full control with on-premises storage if needed. -That way, Bob, Alice and Carol could collaborate using either an S3 bucket remote storage or an ORAS (OCI Registry as Storage) remote storage. -The Cloud Pods command-line interface enables users to manage these remotes with ease, by following the instructions in the -[documentation](/aws/developer-tools/snapshots/cloud-pods#remotes). +That way, Bob, Alice and Carol could collaborate using an S3 bucket for remote storage. +The `lstk` command-line interface enables users to manage this storage with ease, by following the instructions in the +[documentation](/aws/developer-tools/snapshots/saving-snapshots-to-s3). ## Conclusion diff --git a/src/content/docs/aws/tutorials/ecs-ecr-container-app.mdx b/src/content/docs/aws/tutorials/ecs-ecr-container-app.mdx index a31c75ba3..437bf8a77 100644 --- a/src/content/docs/aws/tutorials/ecs-ecr-container-app.mdx +++ b/src/content/docs/aws/tutorials/ecs-ecr-container-app.mdx @@ -1,6 +1,6 @@ --- title: "Deploying containers on Elastic Container Service (ECS) clusters using Elastic Container Registry (ECR) and AWS Fargate, with LocalStack" -description: Set up an NGINX web server via Elastic Container Service (ECS) and Elastic Container Registry (ECR) to serve a static website using LocalStack. Learn how you can use CloudFormation templates to declaratively define, create, and deploy your architecture locally with LocalStack's `awslocal` CLI. +description: Set up an NGINX web server via Elastic Container Service (ECS) and Elastic Container Registry (ECR) to serve a static website using LocalStack. Learn how you can use CloudFormation templates to declaratively define, create, and deploy your architecture locally with LocalStack's `lstk aws` CLI. services: - ecs - ecr @@ -26,7 +26,7 @@ This tutorial will showcase using LocalStack to set up an NGINX web server to se ## Prerequisites - [LocalStack for AWS](https://localstack.cloud/pricing/) -- [awslocal](/aws/connecting/aws-cli#localstack-aws-cli-awslocal) +- [`lstk aws`](/aws/connecting/aws-cli#localstack-aws-cli-lstk-aws) - [Docker](https://docker.io/) - [curl](https://curl.se/download.html) @@ -43,17 +43,17 @@ ENV foo=bar The `Dockerfile` uses the official `nginx` image from Docker Hub, which allows us to serve the default index page. Before building our Docker image, we need to start LocalStack and create an ECR repository to push our Docker image. -To start LocalStack with the `LOCALSTACK_AUTH_TOKEN` environment variable, run the following command: +To start LocalStack, run the following command: ```bash -LOCALSTACK_AUTH_TOKEN= localstack start -d +lstk start ``` Next, we will create an ECR repository to push our Docker image. -We will use the `awslocal` CLI to create the repository. +We will use the `lstk aws` CLI to create the repository. ```bash -awslocal ecr create-repository --repository-name sample-ecr-repo +lstk aws ecr create-repository --repository-name sample-ecr-repo ``` The output of this command will contain the `repositoryUri` value that we'll need in the next step: @@ -360,13 +360,13 @@ Outputs: To deploy the CloudFormation template we created earlier, use the following command: ```bash -awslocal cloudformation create-stack --stack-name infra --template-body file://templates/ecs.infra.yml +lstk aws cloudformation create-stack --stack-name infra --template-body file://templates/ecs.infra.yml ``` Wait until the stack status changes to `CREATE_COMPLETE` by running the following command: ```bash -awslocal cloudformation wait stack-create-complete --stack-name infra +lstk aws cloudformation wait stack-create-complete --stack-name infra ``` You can also check your deployed stack on the LocalStack Web Application by navigating to the [CloudFormation resource browser](https://app.localstack.cloud/resources/cloudformation/stacks). @@ -535,28 +535,28 @@ Resources: Next, let's deploy the CloudFormation template by running the following command: ```bash -awslocal cloudformation create-stack --stack-name ecs --template-body file://templates/ecs.sample.yml --parameters ParameterKey=ImageUrl,ParameterValue= +lstk aws cloudformation create-stack --stack-name ecs --template-body file://templates/ecs.sample.yml --parameters ParameterKey=ImageUrl,ParameterValue= ``` Replace `` with the URI of the Docker image that you want to deploy. Wait for the stack to be created by running the following command: ```bash -awslocal cloudformation wait stack-create-complete --stack-name ecs +lstk aws cloudformation wait stack-create-complete --stack-name ecs ``` Now that the ECS service has been deployed successfully, let's access the application endpoint. First, let's list all the ECS clusters we have deployed in our local environment by running the following command to retrieve the cluster ARN: ```bash -awslocal ecs list-clusters | jq -r '.clusterArns[0]' +lstk aws ecs list-clusters | jq -r '.clusterArns[0]' ``` Save the output of the above command as `CLUSTER_ARN`, as we will use it to list the tasks running in the cluster. Next, run the following command to list the task ARN: ```bash -awslocal ecs list-tasks --cluster | jq -r '.taskArns[0]' +lstk aws ecs list-tasks --cluster | jq -r '.taskArns[0]' ``` Save the task ARN as `TASK_ARN`. @@ -564,7 +564,7 @@ Let us now list the port number on which the application is running. Run the following command: ```bash -awslocal ecs describe-tasks --cluster --tasks | jq -r '.tasks[0].containers[0].networkBindings[0].hostPort' +lstk aws ecs describe-tasks --cluster --tasks | jq -r '.tasks[0].containers[0].networkBindings[0].hostPort' ``` Earlier, we configured the application to run on port `45139`, in our `HostPort` parameter. @@ -581,7 +581,7 @@ You should see the default index page of the NGINX web server. ## Conclusion In this tutorial, we have demonstrated how to deploy a containerized service locally using Amazon ECS, ECR, and LocalStack. -We have also shown how you can use CloudFormation templates with the awslocal CLI to deploy your local AWS infrastructure. +We have also shown how you can use CloudFormation templates with the `lstk aws` CLI to deploy your local AWS infrastructure. With LocalStack, you can easily mount code from your host filesystem into the ECS container, allowing for a quicker debugging loop that doesn't require rebuilding and redeploying the task's Docker image for each change. diff --git a/src/content/docs/aws/tutorials/elb-load-balancing.mdx b/src/content/docs/aws/tutorials/elb-load-balancing.mdx index 801c70386..f54d3c274 100644 --- a/src/content/docs/aws/tutorials/elb-load-balancing.mdx +++ b/src/content/docs/aws/tutorials/elb-load-balancing.mdx @@ -38,7 +38,7 @@ Additionally, we will demonstrate how to set up ELB endpoints to efficiently for - LocalStack for AWS - [Serverless framework](https://www.serverless.com/framework/docs/getting-started/) - [Node.js & `npm`](https://nodejs.org/en/download/) -- [awslocal](https://github.com/localstack/awscli-local) +- [`lstk aws`](/aws/connecting/aws-cli#localstack-aws-cli-lstk-aws) - [curl](https://curl.se/) and [jq](https://jqlang.github.io/jq/) ## Architecture @@ -306,7 +306,7 @@ Now that we have completed the initial setup, let's run LocalStack's AWS emulati Start LocalStack by running the following command: ```bash -LOCALSTACK_AUTH_TOKEN= localstack start -d +lstk start ``` This command launches LocalStack in the background, enabling you to use the AWS services locally. Now, let's deploy our Serverless project and verify the resources created in LocalStack. @@ -344,7 +344,7 @@ This output confirms the successful deployment of your Serverless service to the You can run the following command to verify that the functions and the load balancers have been deployed: ```bash showLineNumbers -awslocal lambda list-functions +lstk aws lambda list-functions { "Functions": [ { @@ -366,7 +366,7 @@ awslocal lambda list-functions ] } -awslocal elbv2 describe-load-balancers +lstk aws elbv2 describe-load-balancers { "LoadBalancers": [ { @@ -391,7 +391,7 @@ The ALB endpoints for the two Lambda functions, hello1 and hello2, are accessibl Here in the testing phase we will test endpoints, do a validation check which includes health check and error handling. To test these endpoints, you can use the curl command along with the jq tool for better formatting. -1. **Verify Deployment:** Use the commands `awslocal lambda list-functions` and `awslocal elbv2 describe-load-balancers` respectively to confirm the existince of Lambda and ALB respectively +1. **Verify Deployment:** Use the commands `lstk aws lambda list-functions` and `lstk aws elbv2 describe-load-balancers` respectively to confirm the existince of Lambda and ALB respectively 2. **Test Endpoints:** Run the following commands: ```bash @@ -404,7 +404,7 @@ Both commands send an HTTP GET request to the endpoints and uses `jq` to format 3. **Health Checks:** Describe target health: ```bash -awslocal elbv2 describe-target-health --target-group-arn $(awslocal elbv2 describe-target-groups --load-balancer-arn $(awslocal elbv2 describe-load-balancers --names lb-test-1 --query 'LoadBalancers[0].LoadBalancerArn' --output text) --query 'TargetGroups[0].TargetGroupArn' --output text) +lstk aws elbv2 describe-target-health --target-group-arn $(lstk aws elbv2 describe-target-groups --load-balancer-arn $(lstk aws elbv2 describe-load-balancers --names lb-test-1 --query 'LoadBalancers[0].LoadBalancerArn' --output text) --query 'TargetGroups[0].TargetGroupArn' --output text) ``` 4. **Invalid Path:** Test fallback/redirect: @@ -414,10 +414,10 @@ curl -I http://lb-test-1.elb.localhost.localstack.cloud:4566/invalid 5. **Logs Validation:** Check Lambda logs for invocations: ```bash -awslocal logs describe-log-groups --query 'logGroups[].logGroupName' | jq -r '.[] | select(contains("hello1"))' | xargs -I {} awslocal logs tail {} --follow +lstk aws logs describe-log-groups --query 'logGroups[].logGroupName' | jq -r '.[] | select(contains("hello1"))' | xargs -I {} lstk aws logs tail {} --follow ``` -If tests fail, you can ensure LocalStack is healthy (`localstack status services`), check ports (default `4566`), and restart if needed. +If tests fail, you can ensure LocalStack is healthy (`lstk status`), check ports (default `4566`), and restart if needed. ## Conclusion diff --git a/src/content/docs/aws/tutorials/ephemeral-application-previews.mdx b/src/content/docs/aws/tutorials/ephemeral-application-previews.mdx index 76c0ab216..243967559 100644 --- a/src/content/docs/aws/tutorials/ephemeral-application-previews.mdx +++ b/src/content/docs/aws/tutorials/ephemeral-application-previews.mdx @@ -30,6 +30,11 @@ This allows you to run end-to-end tests, preview features, and collaborate withi This tutorial will show you how to use LocalStack's Ephemeral Instance feature to generate an Application Preview automatically for every new Pull Request (PR) using a GitHub Action workflow. +:::note +Ephemeral Instances are not supported by [`lstk`](/aws/developer-tools/running-localstack/lstk/). +This tutorial instead uses the [legacy LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/). +::: + ## Architecture diagram of the preview flow ![Ephemeral Previews Flow](/images/aws/empheral_previews_flow.png) diff --git a/src/content/docs/aws/tutorials/iam-policy-stream.mdx b/src/content/docs/aws/tutorials/iam-policy-stream.mdx index 55e155afe..5305b8e85 100644 --- a/src/content/docs/aws/tutorials/iam-policy-stream.mdx +++ b/src/content/docs/aws/tutorials/iam-policy-stream.mdx @@ -19,7 +19,7 @@ When you're developing cloud and serverless applications, you need to grant acce To handle this, you create IAM roles and assign permissions through policies. However, configuring these policies can be challenging, especially if you want to ensure minimal access of all principals to your resources. -[LocalStack IAM Policy Stream](https://app.localstack.cloud/policy-stream) automates the generation of IAM policies for your AWS API requests on your local machine. +[LocalStack IAM Policy Stream](https://app.localstack.cloud/inst/default/policy-stream) automates the generation of IAM policies for your AWS API requests on your local machine. This stream helps you identify the necessary permissions for your cloud application and allows you to detect logical errors, such as unexpected actions in your policies. This tutorial will guide you through setting up IAM Policy Stream for a locally running AWS application. @@ -41,10 +41,10 @@ Additionally, it serves as a useful learning tool, helping users understand the ## Prerequisites -- [LocalStack CLI](/aws/getting-started/installation) with [`LOCALSTACK_AUTH_TOKEN`](/aws/getting-started/auth-token) +- [`lstk`](/aws/getting-started/installation#lstk) with [`LOCALSTACK_AUTH_TOKEN`](/aws/getting-started/auth-token) - [Docker](https://docs.docker.com/get-docker/) -- [Terraform](https://developer.hashicorp.com/terraform/install) & [`tflocal` wrapper](https://github.com/localstack/terraform-local) -- [AWS](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-install.html) CLI with [`awslocal` wrapper](https://github.com/localstack/awscli-local) +- [Terraform](https://developer.hashicorp.com/terraform/install) & [`lstk terraform`](/aws/connecting/infrastructure-as-code/terraform#lstk-terraform) +- [AWS](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-install.html) CLI with [`lstk aws`](/aws/connecting/aws-cli#localstack-aws-cli-lstk-aws) - [LocalStack account](https://www.localstack.cloud/pricing) - [`jq`](https://jqlang.github.io/jq/download/) @@ -74,13 +74,13 @@ With LocalStack's IAM enforcement enabled, you can thoroughly test your policy a Launch the LocalStack container on your local machine using the specified command: ```bash -DEBUG=1 IAM_SOFT_MODE=1 localstack start +LOCALSTACK_DEBUG=1 LOCALSTACK_IAM_SOFT_MODE=1 lstk start ``` In the above command: -- `DEBUG=1` turns on detailed logging to check API calls and IAM violations. -- `IAM_SOFT_MODE=1` lets you test IAM enforcement by logging violations without stopping the API calls. +- `LOCALSTACK_DEBUG=1` turns on detailed logging to check API calls and IAM violations. +- `LOCALSTACK_IAM_SOFT_MODE=1` lets you test IAM enforcement by logging violations without stopping the API calls. ### Create the Terraform configuration @@ -116,12 +116,12 @@ resource "aws_s3_bucket_notification" "bucket_notification" { ### Deploy the Terraform configuration -You can use `tflocal` to deploy your Terraform configuration within the LocalStack environment. +You can use `lstk terraform` to deploy your Terraform configuration within the LocalStack environment. Run the following commands to initialize and apply the Terraform configuration: ```bash -tflocal init -tflocal apply +lstk terraform init +lstk terraform apply ``` You will be prompted to confirm the changes. @@ -145,7 +145,7 @@ Apply complete! Resources: 3 added, 0 changed, 0 destroyed. ### Start the IAM Policy Stream -Access the [LocalStack Web Application](https://app.localstack.cloud/) and go to the [IAM Policy Stream dashboard](https://app.localstack.cloud/policy-stream). +Access the [LocalStack Web Application](https://app.localstack.cloud/) and go to the [IAM Policy Stream dashboard](https://app.localstack.cloud/inst/default/policy-stream). This feature enables you to directly examine the generated policies, displaying the precise permissions required for each API call. ![IAM Policy Stream dashboard](/images/aws/iam-policy-stream-dashboard.png) @@ -159,11 +159,11 @@ Create a new file named `some-log-file.log` and upload it to the S3 bucket using ```bash echo "Hello, LocalStack" > some-log-file.log -awslocal s3 cp some-log-file.log s3://s3-event-notification-bucket/ +lstk aws s3 cp some-log-file.log s3://s3-event-notification-bucket/ ``` Uploading a file will activate an event notification, sending a message to the SQS queue. -However, since the SQS queue lacks the necessary permissions, an IAM violation will appear in the [IAM Policy Stream dashboard](https://app.localstack.cloud/policy-stream). +However, since the SQS queue lacks the necessary permissions, an IAM violation will appear in the [IAM Policy Stream dashboard](https://app.localstack.cloud/inst/default/policy-stream). ![IAM Policy Stream showcasing an IAM violation](/images/aws/iam-policy-stream-violation.png) @@ -221,14 +221,14 @@ POLICY Now, re-apply the Terraform configuration to update the SQS queue with the new policy: ```bash -tflocal apply +lstk terraform apply ``` Next, trigger the event notification again by uploading a file to the S3 bucket. You can confirm that the S3 bucket is correctly set up for event notifications through the SQS queue by checking if the message is received in the SQS queue: ```bash -awslocal sqs receive-message \ +lstk aws sqs receive-message \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/s3-event-notification-queue ``` @@ -273,13 +273,13 @@ This section demonstrates how to test your IAM policies and verify both deny and ### Testing Scenario 1: Deny (Without IAM Policy) -When you first upload a file to the S3 bucket without the proper SQS queue policy in place, the S3 service will be denied permission to send messages to the SQS queue. +When you first upload a file to the S3 bucket without the proper SQS queue policy in place, S3 has no permission to send messages to the SQS queue, and the violation is reported. **Upload a test file:** ```bash echo "Test file content" > test-file.log -awslocal s3 cp test-file.log s3://s3-event-notification-bucket/ +lstk aws s3 cp test-file.log s3://s3-event-notification-bucket/ ``` **Expected output - IAM Violation in LocalStack logs:** @@ -305,19 +305,28 @@ The dashboard clearly shows: **Attempting to receive messages from the queue:** ```bash -awslocal sqs receive-message \ +lstk aws sqs receive-message \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/s3-event-notification-queue ``` -**Expected output - No messages (because S3 was denied):** +**Expected output - the message is still delivered, because soft mode does not block the call:** ```json { - "Messages": [] + "Messages": [ + { + "MessageId": "5da627c5-5b4b-4202-a499-510222727e43", + "ReceiptHandle": "NWMyZDA1MDEtM2NlYi00MzBjLWIyNjQtYjM2ZjNmYmQxZTAyIGFybjphd3M6c3FzOnVzLWVhc3QtMTowMDAwMDAwMDAwMDA6czMtZXZlbnQtbm90aWZpY2F0aW9uLXF1ZXVlIDVkYTYyN2M1LTViNGItNDIwMi1hNDk5LTUxMDIyMjcyN2U0MyAxNzg2NjY1NzQ3LjQ3ODI1MTI=", + "MD5OfBody": "dee5cf145a0678a0ac02e3b38aa302f7", + "Body": "{\"Records\": [{\"eventVersion\": \"2.1\", \"eventSource\": \"aws:s3\", \"awsRegion\": \"us-east-1\", \"eventName\": \"ObjectCreated:Put\", \"s3\": {\"bucket\": {\"name\": \"s3-event-notification-bucket\"}, \"object\": {\"key\": \"test-file.log\", \"size\": 18}}}]}" + } + ] } ``` -Or you may receive no output at all, indicating an empty queue. +:::note +In a production environment, where the same policy gap would be enforced by real AWS IAM, this `SendMessage` call would fail and the message would never arrive. +::: ### Testing Scenario 2: Allow (With IAM Policy) @@ -353,7 +362,7 @@ After applying the IAM policy generated by the Policy Stream to your SQS queue, ```bash echo "Test file with policy" > test-file-2.log -awslocal s3 cp test-file-2.log s3://s3-event-notification-bucket/ +lstk aws s3 cp test-file-2.log s3://s3-event-notification-bucket/ ``` **Expected output - Success (no IAM violation):** @@ -362,13 +371,16 @@ awslocal s3 cp test-file-2.log s3://s3-event-notification-bucket/ upload: ./test-file-2.log to s3://s3-event-notification-bucket/test-file-2.log ``` -**LocalStack logs showing successful permission:** +**LocalStack logs:** -```shell -2024-07-09T05:35:22.123 DEBUG --- [et.reactor-2] l.s.i.p.handler : Request for service 'sqs' by principal 's3.amazonaws.com' for operation 'SendMessage' allowed. -2024-07-09T05:35:22.123 DEBUG --- [et.reactor-2] l.s.i.p.handler : 1 permissions have been explicitly allowed: ["Action 'sqs:SendMessage' for 'arn:aws:sqs:us-east-1:000000000000:s3-event-notification-queue'"] +An allowed request produces no output from the IAM policy handler — only denials are logged. + +```bash +lstk logs | grep "i.p.handler" ``` +Only the entries from the earlier, un-permitted upload should remain. + **IAM Policy Stream Dashboard showing no violations:** ![IAM Policy Stream showcasing no violations](/images/aws/iam-policy-stream-no-violations.png) @@ -378,7 +390,7 @@ The dashboard shows all actions with green checkmarks, indicating successful exe **Receive the message from the queue:** ```bash -awslocal sqs receive-message \ +lstk aws sqs receive-message \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/s3-event-notification-queue ``` @@ -405,7 +417,7 @@ To ensure your IAM policies are correctly configured: - **No IAM violations** appear in the IAM Policy Stream dashboard - **Messages are successfully delivered** to the SQS queue -- **LocalStack logs show "allowed"** for the `SendMessage` operation +- **No new violation entries** are logged for the `SendMessage` operation after the policy is applied - **All API calls display green checkmarks** in the Policy Stream dashboard ## Conclusion diff --git a/src/content/docs/aws/tutorials/java-notification-app.mdx b/src/content/docs/aws/tutorials/java-notification-app.mdx index ed022d7ef..1d1607a46 100644 --- a/src/content/docs/aws/tutorials/java-notification-app.mdx +++ b/src/content/docs/aws/tutorials/java-notification-app.mdx @@ -37,7 +37,7 @@ For this tutorial, you will need: - [LocalStack for AWS](https://localstack.cloud/pricing/) to emulate the AWS services (SNS, SQS, SES, etc) locally - Don't worry, if you don't have a subscription yet, you can just get a trial license for free. -- [awslocal](/aws/connecting/aws-cli#localstack-aws-cli-awslocal) +- [`lstk aws`](/aws/connecting/aws-cli#localstack-aws-cli-lstk-aws) - [Docker](https://docker.io/) - Java 11+ - Maven 3+ @@ -550,10 +550,16 @@ You can start LocalStack using the following command: LOCALSTACK_AUTH_TOKEN= docker-compose up -d ``` +Given that you've started LocalStack via `docker-compose`, you'll need to configure the `lstk` CLI to contact your container: + +```bash +export LSTK_ENDPOINT_URL=http://localhost.localstack.cloud:4566 +``` + Once LocalStack is started, we can deploy the CloudFormation stack (which might take a few moments): ```bash -awslocal cloudformation deploy \ +lstk aws cloudformation deploy \ --template-file src/main/resources/email-infra.yml \ --stack-name email-infra ``` @@ -570,13 +576,13 @@ AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test mvn spring-boot:run To get started, we will an add email address to the list of identities for our mocked SES account to verify the email address: ```bash -awslocal ses verify-email-identity --email-address no-reply@localstack.cloud +lstk aws ses verify-email-identity --email-address no-reply@localstack.cloud ``` Let us now send a message to the topic: ```bash -awslocal sns publish \ +lstk aws sns publish \ --topic arn:aws:sns:us-east-1:000000000000:email-notifications \ --message '{"subject":"hello", "address": "alice@example.com", "body": "hello world"}' ``` diff --git a/src/content/docs/aws/tutorials/lambda-ecr-container-images.mdx b/src/content/docs/aws/tutorials/lambda-ecr-container-images.mdx index cbb4af4a7..197fc366a 100644 --- a/src/content/docs/aws/tutorials/lambda-ecr-container-images.mdx +++ b/src/content/docs/aws/tutorials/lambda-ecr-container-images.mdx @@ -33,7 +33,7 @@ In this tutorial, we will explore creating a Lambda function using a container i Before diving into this tutorial, make sure you have the following prerequisites: - [LocalStack for AWS](https://localstack.cloud/pricing/) -- [awslocal](/aws/connecting/aws-cli#localstack-aws-cli-awslocal) +- [`lstk aws`](/aws/connecting/aws-cli#localstack-aws-cli-lstk-aws) - [Python](https://www.python.org/downloads/) - [Docker](https://docker.io/) @@ -106,18 +106,17 @@ The resulting image will contain your function code and any specified dependenci Now that the initial setup is complete let's explore how to leverage LocalStack's AWS emulation by pushing our image to ECR and deploying the Lambda container image. Start LocalStack by executing the following command. -Make sure to replace `` with your actual Auth Token: ```bash -LOCALSTACK_AUTH_TOKEN= ECR_ENDPOINT_STRATEGY=off DEBUG=1 localstack start -d +LOCALSTACK_ECR_ENDPOINT_STRATEGY=off LOCALSTACK_DEBUG=1 lstk start ``` Once the LocalStack container is running, we can create a new ECR repository to store our container image. -Use the `awslocal` CLI to achieve this. +Use the `lstk aws` CLI to achieve this. Run the following command to create the repository, replacing `localstack-lambda-container-image` with the desired name for your repository: ```bash -awslocal ecr create-repository --repository-name localstack-lambda-container-image +lstk aws ecr create-repository --repository-name localstack-lambda-container-image ``` ```bash title="Output" @@ -156,7 +155,7 @@ In the above commands, we specify the `repositoryUri` as the image name to push After executing these commands, you can verify that the image is successfully pushed to the repository by using the `describe-images` command: ```bash -awslocal ecr describe-images --repository-name localstack-lambda-container-image +lstk aws ecr describe-images --repository-name localstack-lambda-container-image ``` ```bash title="Output" @@ -193,7 +192,7 @@ More information can be found [in our documentation regarding ARM support.](/aws ::: ```bash -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name localstack-lambda-container-image \ --package-type Image \ --code ImageUri="localhost.localstack.cloud:4510/localstack-lambda-container-image" \ @@ -253,7 +252,7 @@ Here's an explanation of each flag: To invoke the Lambda function, you can use the `invoke` command: ```bash -awslocal lambda invoke --function-name localstack-lambda-container-image /tmp/lambda.out +lstk aws lambda invoke --function-name localstack-lambda-container-image /tmp/lambda.out ``` ```bash title="Output" diff --git a/src/content/docs/aws/tutorials/rds-database-initialization.mdx b/src/content/docs/aws/tutorials/rds-database-initialization.mdx index 32975645d..ec306468c 100644 --- a/src/content/docs/aws/tutorials/rds-database-initialization.mdx +++ b/src/content/docs/aws/tutorials/rds-database-initialization.mdx @@ -28,8 +28,8 @@ In this tutorial, we will demonstrate how to provision and initialize an Amazon For this tutorial, you will need: - [LocalStack for AWS](https://localstack.cloud/pricing/) with a valid auth token -- [AWS CLI](https://docs.localstack.cloud/user-guide/integrations/aws-cli/) with the [`awslocal` wrapper](https://docs.localstack.cloud/user-guide/integrations/aws-cli/#localstack-aws-cli-awslocal) -- [AWS CDK](https://docs.localstack.cloud/user-guide/integrations/aws-cdk/) with the [`cdklocal`](https://www.npmjs.com/package/aws-cdk-local) wrapper +- [AWS CLI](https://docs.localstack.cloud/user-guide/integrations/aws-cli/) with the [`lstk aws`](/aws/connecting/aws-cli#localstack-aws-cli-lstk-aws) command +- [AWS CDK](https://docs.localstack.cloud/user-guide/integrations/aws-cdk/) with the [`lstk cdk`](/aws/connecting/infrastructure-as-code/aws-cdk#aws-cdk-cli-for-localstack) command - [Node.js](https://nodejs.org/en/download/) (version 16 or later) - [Docker](https://docker.io/) - MySQL or PostgreSQL client (for testing database connections) @@ -79,8 +79,7 @@ make install Start LocalStack with your auth token: ```bash -localstack auth set-token -localstack start +lstk start ``` > **Note**: By default, LocalStack uses the MariaDB engine for RDS (see [RDS documentation](https://docs.localstack.cloud/user-guide/aws/rds/#mysql-engine)). To use the real MySQL engine in a separate Docker container, set the environment variable `RDS_MYSQL_DOCKER=1`. @@ -92,7 +91,7 @@ Deploy the sample application using CDK: ```bash make deploy # or manually: -cdklocal deploy +lstk cdk deploy ``` The deployment process will: @@ -133,7 +132,7 @@ The deployed Lambda function `my-lambda-rds-query-helper` can execute SQL querie **For AWS CLI v1:** ```bash -awslocal lambda invoke \ +lstk aws lambda invoke \ --function-name my-lambda-rds-query-helper \ --payload '{"sqlQuery": "select Author from books", "secretName":"/rdsinitexample/rds/creds/mysql-01"}' \ output @@ -141,7 +140,7 @@ awslocal lambda invoke \ **For AWS CLI v2:** ```bash -awslocal lambda invoke \ +lstk aws lambda invoke \ --cli-binary-format raw-in-base64-out \ --function-name my-lambda-rds-query-helper \ --payload '{"sqlQuery": "select Author from books", "secretName":"/rdsinitexample/rds/creds/mysql-01"}' \ @@ -169,7 +168,7 @@ You can also run more detailed queries to explore the data: **Query all book details:** ```bash -awslocal lambda invoke \ +lstk aws lambda invoke \ --cli-binary-format raw-in-base64-out \ --function-name my-lambda-rds-query-helper \ --payload '{"sqlQuery": "SELECT * FROM books LIMIT 5", "secretName":"/rdsinitexample/rds/creds/mysql-01"}' \ @@ -182,7 +181,7 @@ Test various database operations to verify the initialization: **Check table structure:** ```bash -awslocal lambda invoke \ +lstk aws lambda invoke \ --cli-binary-format raw-in-base64-out \ --function-name my-lambda-rds-query-helper \ --payload '{"sqlQuery": "DESCRIBE books", "secretName":"/rdsinitexample/rds/creds/mysql-01"}' \ @@ -191,7 +190,7 @@ awslocal lambda invoke \ **Count records:** ```bash -awslocal lambda invoke \ +lstk aws lambda invoke \ --cli-binary-format raw-in-base64-out \ --function-name my-lambda-rds-query-helper \ --payload '{"sqlQuery": "SELECT COUNT(*) as total_books FROM books", "secretName":"/rdsinitexample/rds/creds/mysql-01"}' \ @@ -200,7 +199,7 @@ awslocal lambda invoke \ **Filter by author:** ```bash -awslocal lambda invoke \ +lstk aws lambda invoke \ --cli-binary-format raw-in-base64-out \ --function-name my-lambda-rds-query-helper \ --payload '{"sqlQuery": "SELECT title, published_year FROM books WHERE author = \"George Orwell\"", "secretName":"/rdsinitexample/rds/creds/mysql-01"}' \ @@ -213,10 +212,10 @@ For more comprehensive testing, you can connect directly to the RDS instance usi ```bash # Get the database endpoint -awslocal rds describe-db-instances --query 'DBInstances[0].Endpoint.Address' --output text +lstk aws rds describe-db-instances --query 'DBInstances[0].Endpoint.Address' --output text # Get credentials from Secrets Manager -awslocal secretsmanager get-secret-value --secret-id /rdsinitexample/rds/creds/mysql-01 --query SecretString --output text +lstk aws secretsmanager get-secret-value --secret-id /rdsinitexample/rds/creds/mysql-01 --query SecretString --output text ``` Connect using the MySQL command-line client: diff --git a/src/content/docs/aws/tutorials/reproducible-machine-learning-cloud-pods.mdx b/src/content/docs/aws/tutorials/reproducible-machine-learning-cloud-pods.mdx index ccdd8f973..f55147da6 100644 --- a/src/content/docs/aws/tutorials/reproducible-machine-learning-cloud-pods.mdx +++ b/src/content/docs/aws/tutorials/reproducible-machine-learning-cloud-pods.mdx @@ -17,11 +17,10 @@ leadimage: "reproducible-machine-learning-cloud-pods-featured-image.png" [LocalStack Cloud Pods](/aws/developer-tools/snapshots/cloud-pods) enable you to create persistent state snapshots of your LocalStack instance, which can then be versioned, shared, and restored. It allows next-generation state management and team collaboration for your local cloud development environment, which you can utilize to create persistent shareable cloud sandboxes. -Cloud Pods works directly with the [LocalStack CLI](/aws/connecting/aws-cli#localstack-aws-cli-awslocal) to save, merge, and restore snapshots of your LocalStack state. +Cloud Pods works directly with the [`lstk`](/aws/developer-tools/running-localstack/lstk/) CLI to save, merge, and restore snapshots of your LocalStack state. You can always tear down your LocalStack instance and restore it from a snapshot at any point in time. -Cloud Pods is supported in [LocalStack Team](https://app.localstack.cloud/). -With LocalStack Team, you can utilize the Cloud Pods CLI that allows you to inspect your Cloud Pods, version them using tags, and push them to the LocalStack platform for storage and collaboration. +The `lstk snapshot` commands allow you to inspect your Cloud Pods, version them, and push them to the LocalStack platform for storage and collaboration. In this tutorial, we will use [LocalStack for AWS](/aws/getting-started/auth-token) to train a simple machine-learning model that recognizes handwritten digits on an image. We will rely on Cloud Pods to create a reproducible sample by using: @@ -40,12 +39,11 @@ We will then create a Cloud Pod to save the state of our LocalStack instance and For this tutorial, you will need the following: - [LocalStack for AWS](https://localstack.cloud/pricing/) -- [awslocal](/aws/connecting/aws-cli#localstack-aws-cli-awslocal) +- [`lstk aws`](/aws/connecting/aws-cli#localstack-aws-cli-lstk-aws) - [Optical recognition of handwritten digits dataset](https://github.com/localstack-samples/localstack-pro-samples/raw/refs/heads/master/reproducible-ml/digits.csv.gz) ([Source](https://archive.ics.uci.edu/ml/datasets/Optical+Recognition+of+Handwritten+Digits)) If you don't have a subscription to LocalStack for AWS, you can request a trial license upon sign-up. -For this tutorial to work, you must have the LocalStack CLI installed, which must be version 1.3 or higher. -The Cloud Pods CLI is shipped with the LocalStack CLI, so you don't need to install it separately. +For this tutorial to work, you must have [`lstk`](/aws/getting-started/installation#lstk) installed. ## Training the machine learning model @@ -189,28 +187,29 @@ Before creating our Lambda functions, let us start LocalStack to use emulated S3 Let's start LocalStack: ```bash -DEBUG=1 LOCALSTACK_AUTH_TOKEN= localstack start -d +LOCALSTACK_DEBUG=1 lstk start ``` -We have specified `DEBUG=1` to get the printed LocalStack logs from our Lambda invocation in the console. +We have specified `LOCALSTACK_DEBUG=1` so that the logs from our Lambda invocations are recorded by LocalStack. +Since `lstk start` runs the emulator in the background, we will read those logs with `lstk logs`. We can now create an S3 bucket to upload our Lambda functions and the dataset: ```bash zip lambda.zip train.py zip infer.zip infer.py -awslocal s3 mb s3://reproducible-ml -awslocal s3 cp lambda.zip s3://reproducible-ml/lambda.zip -awslocal s3 cp infer.zip s3://reproducible-ml/infer.zip -awslocal s3 cp digits.csv.gz s3://reproducible-ml/digits.csv.gz +lstk aws s3 mb s3://reproducible-ml +lstk aws s3 cp lambda.zip s3://reproducible-ml/lambda.zip +lstk aws s3 cp infer.zip s3://reproducible-ml/infer.zip +lstk aws s3 cp digits.csv.gz s3://reproducible-ml/digits.csv.gz ``` In the above commands, we first create two zip files for our Lambda functions: lambda.zip and infer.zip. These zip files contain the code for training the machine learning model and do predictions with it, respectively. Next, we create an S3 bucket called `reproducible-ml` and upload the zip files and the dataset to it. -Finally, we use the `awslocal` CLI to create the two Lambda functions +Finally, we use the `lstk aws` CLI to create the two Lambda functions ```bash -awslocal lambda create-function --function-name ml-train \ +lstk aws lambda create-function --function-name ml-train \ --runtime python3.8 \ --role arn:aws:iam::000000000000:role/lambda-role \ --handler train.handler \ @@ -220,7 +219,7 @@ awslocal lambda create-function --function-name ml-train \ ``` ```bash -awslocal lambda create-function --function-name ml-predict \ +lstk aws lambda create-function --function-name ml-predict \ --runtime python3.8 \ --role arn:aws:iam::000000000000:role/lambda-role \ --handler infer.handler \ @@ -233,111 +232,116 @@ For each function, we provide the function name, runtime (`python3.8`), handler We have also specified the `python-3-8-scikit-learn-0-23-1` layer to be used by the Lambda function. This layer includes the scikit-learn library and its dependencies. -We can now invoke the first Lambda function using the `awslocal` CLI: +We can now invoke the first Lambda function using the `lstk aws` CLI: ```bash -awslocal lambda invoke --function-name ml-train /tmp/test.tmp +lstk aws lambda invoke --function-name ml-train /tmp/test.tmp ``` The first Lambda function will train the model and upload it to the S3 bucket. Finally, we can invoke the second Lambda function to do predictions with the model. ```bash -awslocal lambda invoke --function-name ml-predict /tmp/test.tmp +lstk aws lambda invoke --function-name ml-predict /tmp/test.tmp ``` -The logs of the Lambda invocation should be visible in the LocalStack container output (with `DEBUG=1` enabled): +Each `invoke` call writes the function's return value to `/tmp/test.tmp` and prints the invocation status: + +```bash title="Output" +{ + "StatusCode": 200, + "ExecutedVersion": "$LATEST" +} +``` + +The prediction output itself is logged by LocalStack (with `LOCALSTACK_DEBUG=1` enabled). +Retrieve it with the `logs` command: ```bash -null ->START RequestId: 65dc894d-25e0-168e-dea1-a3e8bfdb563b Version: $LATEST -> --> prediction result: [8 8 4 9 0 8 9 8 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 9 6 7 8 9 -... +lstk logs +``` + +```bash title="Output" +2026-08-18T20:06:25.174 DEBUG --- [et.reactor-2] l.p.c.s.l.i.version_manage : [ml-predict-f5e813df-cc00-41ef-bb88-5075f4d05ff7] START RequestId: f5e813df-cc00-41ef-bb88-5075f4d05ff7 Version: $LATEST +2026-08-18T20:06:25.174 DEBUG --- [et.reactor-2] l.p.c.s.l.i.version_manage : [ml-predict-f5e813df-cc00-41ef-bb88-5075f4d05ff7] --> prediction result: [8 8 4 9 0 8 9 8 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 9 6 7 8 9 ... -> 9 5 4 8 8 4 9 0 8 9 8] -> END RequestId: 6... +2026-08-18T20:06:25.177 DEBUG --- [et.reactor-2] l.p.c.s.l.i.version_manage : [ml-predict-f5e813df-cc00-41ef-bb88-5075f4d05ff7] 9 5 4 8 8 4 9 0 8 9 8] +2026-08-18T20:06:25.178 DEBUG --- [et.reactor-2] l.p.c.s.l.i.version_manage : [ml-predict-f5e813df-cc00-41ef-bb88-5075f4d05ff7] END RequestId: f5e813df-cc00-41ef-bb88-5075f4d05ff7 ``` +You can also stream the logs with `lstk logs --follow`. + ## Creating a Cloud Pod After deploying the Lambda functions, we can create a Cloud Pod to share our local infrastructure and instance state with other LocalStack users in the organization. To save the current state of our LocalStack instance, we can use the `save` command: ```bash -localstack pod save reproducible-ml +lstk snapshot save pod:reproducible-ml ``` ```bash title="Output" -Cloud Pod reproducible-ml successfully created +Saving snapshot to pod "reproducible-ml"...... +✔︎ Snapshot saved to pod:reproducible-ml +• Version: 1 +• Services: lambda, cloudwatch, logs, s3, sts +• Size: 40.8 MB ``` :::note -You can also export a Cloud Pod locally by specifying a file URI as an argument. +You can also save a snapshot locally by specifying a plain path as an argument, instead of a `pod:` destination. To export on a local path, run the following command: ```bash -localstack pod save file:/// +lstk snapshot save / ``` -The output of the above command will be a `` zip file in the specified directory. +The output of the above command will be a `.snapshot` file in the specified directory. We can restore it at any time with the `load` command. ::: To list available the Cloud Pods you can use the `list` command: ```bash -localstack pod list +lstk snapshot list ``` ```bash title="Output" -┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓ -┃ local/remote ┃ Name ┃ -┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━┩ -│ local+remote │ reproducible-ml │ -└──────────────┴─────────────────┘ +Fetching snapshots... +~ 1 snapshots + + NAME VERSION LAST CHANGED + reproducible-ml 1 2026-08-18 20:08 UTC ``` -You can also inspect the contents of a Cloud Pod using the `inspect` command: +You can also inspect the contents of a Cloud Pod using the `show` command: ```bash -localstack pod inspect reproducible-ml +lstk snapshot show pod:reproducible-ml ``` While you save a Cloud Pod, it is automatically published on the LocalStack platform and can be shared with other users in your organization. While saving an already existing Cloud Pod, we would create a new version, which is eventually uploaded to the LocalStack platform. -:::note -You can optionally set the visibility of a Cloud Pod to `private` or `public` using the `--visibility` flag. -By default, the visibility of a Cloud Pod is set to `private`. -To set a Cloud Pod to `public`, you can use the following command: - -```bash -localstack pod save --name --visibility public -``` - -The above command does not create a new version and requires a version already registered with the platform. -::: -You can also attach an optional message and a list of services to a Cloud Pod using the `--message` and `--services` flags. You can check all the Cloud Pods in your organization over the [LocalStack Web Application](https://app.localstack.cloud/pods). Now that we have created a Cloud Pod, we can ask one of our team members to start LocalStack and load the Cloud Pod using the `load` command. ```bash -localstack pod load reproducible-ml +lstk snapshot load pod:reproducible-ml ``` The `load` command will retrieve the content of our Cloud Pod named `reproducible-ml` from the LocalStack platform and inject it into our running LocalStack instance. Upon successfully loading the Cloud Pod, the Lambda function can be invoked again, and the log output should be the same as before. -LocalStack Cloud Pods also feature different merge strategies to merge the state of a Cloud Pod with the current LocalStack instance. +LocalStack Cloud Pods also feature different [merge strategies](/aws/developer-tools/snapshots/merging-snapshots/) to merge the state of a Cloud Pod with the current LocalStack instance. You can use the `--merge` flag to specify the merge strategy. The available merge strategies are: -- **Load with overwrite**: This is the default merge strategy. - It will load the state of the Cloud Pod into the current LocalStack instance and overwrite the existing state. -- **Load with basic merge**: This merge strategy will load the state of the Cloud Pod into the current LocalStack instance and merge the existing state with the state of the Cloud Pod. -- **Load with deep merge**: This merge strategy will load the state of the Cloud Pod into the current LocalStack instance and merge the existing state with the state of the Cloud Pod. - It will also merge the existing state with the state of the Cloud Pod recursively. +- **`account-region-merge`**: This is the default merge strategy. + The state of the Cloud Pod wins wherever it overlaps with the running state on a (service, account, region) combination. +- **`overwrite`**: This merge strategy wipes the running state, then loads the state of the Cloud Pod into the current LocalStack instance. +- **`service-merge`**: This merge strategy combines non-overlapping resources, and the state of the Cloud Pod wins on a per-resource basis. ![State Merge mechanisms with LocalStack Cloud Pods](/images/aws/cloud-pods-state-merge-mechanisms.png) @@ -347,19 +351,19 @@ After deploying and invoking the Lambdas, first verify the end-to-end ML workflo ### Expected Outputs from Training -Invoke `ml-train` with: `awslocal lambda invoke --function-name ml-train /tmp/test.tmp` +Invoke `ml-train` with: `lstk aws lambda invoke --function-name ml-train /tmp/test.tmp` - Logs show dataset load (1797 samples), training on 50% split, and S3 uploads for `model.joblib` and `test-set.npy`. - No explicit accuracy during training (focus is on savings), but the SVM classifier fits successfully. ### Expected Outputs from Inference (ml-predict Invocation) -Invoke `ml-predict` with: `awslocal lambda invoke --function-name ml-predict /tmp/test.tmp` +Invoke `ml-predict` with: `lstk aws lambda invoke --function-name ml-predict /tmp/test.tmp` - Downloads model and test set from S3. - Runs predictions on the test set (898 samples). - **Sample prediction result** (first 20): `[8 8 4 9 0 8 9 8 1 2 3 4 5 6 7 8 9 0 1 2]` -- **Expected accuracy**: ~96.9% (calculated as `accuracy_score(y_test, predicted)`—e.g., 870/898 correct). Full logs in LocalStack output (with `DEBUG=1`): +- **Expected accuracy**: ~96.9% (calculated as `accuracy_score(y_test, predicted)`—e.g., 870/898 correct). Full logs in LocalStack output (with `LOCALSTACK_DEBUG=1`): --> prediction result: [8 8 4 9 0 8 9 8 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 9 6 7 8 9 ... 9 5 4 8 8 4 9 0 8 9 8] @@ -377,11 +381,11 @@ Expected Model accuracy: 0.9689 ### Validation After Pod Restore -- Save Pod: `localstack pod save reproducible-ml` -- (In a new instance) Load: `localstack pod load reproducible-ml` +- Save Pod: `lstk snapshot save pod:reproducible-ml` +- (In a new instance) Load: `lstk snapshot load pod:reproducible-ml` - Re-invoke `ml-predict`: Outputs should match exactly, proving state persistence (S3 objects, Lambdas intact). -If a mismatch occurs, check the Pod's merge strategy `(default: overwrite)` or logs for S3/Lambda errors. +If a mismatch occurs, check the Pod's merge strategy `(default: account-region-merge)` or logs for S3/Lambda errors. ## Conclusion diff --git a/src/content/docs/aws/tutorials/route-53-failover.mdx b/src/content/docs/aws/tutorials/route-53-failover.mdx index 657752293..f0f1df69f 100644 --- a/src/content/docs/aws/tutorials/route-53-failover.mdx +++ b/src/content/docs/aws/tutorials/route-53-failover.mdx @@ -32,7 +32,7 @@ In this example, there's an active-primary and passive-standby configuration. Route53 routes traffic to the primary region, which processes product-related requests through API Gateway and Lambda functions, with data stored in DynamoDB. If the primary region fails, Route53 redirects to the standby region, maintained in sync by a replication Lambda function. -For this particular example, we'll be using a [sample application repository](https://github.com/localstack-samples/samples-chaos-engineering/tree/main/route53-failover). +For this particular example, we'll be using a [sample application repository](https://github.com/localstack-samples/sample-chaos-serverless-multi-region-failover). Clone the repository, and follow the instructions below to get started. ### Prerequisites @@ -40,7 +40,7 @@ Clone the repository, and follow the instructions below to get started. The general prerequisites for this guide are: - LocalStack for AWS with [LocalStack Auth Token](/aws/getting-started/auth-token) -- [AWS CLI](/aws/connecting/aws-cli) with the [`awslocal` wrapper](/aws/connecting/aws-cli#localstack-aws-cli-awslocal) +- [AWS CLI](/aws/connecting/aws-cli) with the [`lstk aws`](/aws/connecting/aws-cli#localstack-aws-cli-lstk-aws) command - [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) - [Python-3](https://www.python.org/downloads/) - `dig` @@ -53,6 +53,12 @@ LOCALSTACK_AUTH_TOKEN= docker compose up ``` +Given that you've started LocalStack via `docker-compose`, you'll need to configure the `lstk` CLI to contact your container: + +```bash +export LSTK_ENDPOINT_URL=http://localhost.localstack.cloud:4566 +``` + ### Architecture The following diagram shows the architecture that this application builds and deploys: @@ -80,14 +86,14 @@ Let's begin by setting up a hosted zone in Route53 named `hello-localstack.com` ```bash HOSTED_ZONE_NAME=hello-localstack.com -HOSTED_ZONE_ID=$(awslocal route53 create-hosted-zone --name $HOSTED_ZONE_NAME --caller-reference foo | jq -r .HostedZone.Id) +HOSTED_ZONE_ID=$(lstk aws route53 create-hosted-zone --name $HOSTED_ZONE_NAME --caller-reference foo | jq -r .HostedZone.Id) ``` Then, define the health check ID for the API Gateway available in the `us-west-1` region: ```bash HEALTH_CHECK_ID=$( -awslocal route53 create-health-check \ +lstk aws route53 create-health-check \ --caller-reference foobar \ --health-check-config '{ "FullyQualifiedDomainName": "12345.execute-api.localhost.localstack.cloud", @@ -106,7 +112,7 @@ To update DNS records in the specified Route53 hosted zone (`$HOSTED_ZONE_ID`), Set a TTL (Time to Live) of 60 seconds for these records. ```bash -awslocal route53 change-resource-record-sets \ +lstk aws route53 change-resource-record-sets \ --hosted-zone $HOSTED_ZONE_ID \ --change-batch '{ "Changes": [ @@ -142,7 +148,7 @@ The first record points to `12345.$HOSTED_ZONE_NAME` and is linked with the earl The second record points to `67890.$HOSTED_ZONE_NAME` and is set as the secondary failover target. ```bash -awslocal route53 change-resource-record-sets \ +lstk aws route53 change-resource-record-sets \ --hosted-zone-id $HOSTED_ZONE_ID \ --change-batch '{ "Changes": [ diff --git a/src/content/docs/aws/tutorials/s3-static-website-terraform.mdx b/src/content/docs/aws/tutorials/s3-static-website-terraform.mdx index c0fc0167a..291828046 100644 --- a/src/content/docs/aws/tutorials/s3-static-website-terraform.mdx +++ b/src/content/docs/aws/tutorials/s3-static-website-terraform.mdx @@ -1,7 +1,7 @@ --- title: "Host a static website locally using Simple Storage Service (S3) and Terraform with LocalStack" description: > - Host a static website using a Simple Storage Service (S3) bucket to serve static content by provisioning the infrastructure using Terraform in LocalStack. Learn how to configure S3 buckets locally for testing and integration, and make use of LocalStack's S3 API & `tflocal` CLI to provision infrastructure locally. + Host a static website using a Simple Storage Service (S3) bucket to serve static content by provisioning the infrastructure using Terraform in LocalStack. Learn how to configure S3 buckets locally for testing and integration, and make use of LocalStack's S3 API & `lstk terraform` CLI to provision infrastructure locally. services: - s3 platform: @@ -26,15 +26,15 @@ LocalStack also supports the creation of S3 buckets with static website hosting In this tutorial, we will deploy a static website using an S3 bucket over a locally emulated AWS infrastructure on LocalStack. We will use Terraform to automate the creation & management of AWS resources by declaring them in the HashiCorp Configuration Language (HCL). -We will also learn about `tflocal`, a CLI wrapper created by LocalStack, that allows you to run Terraform locally against LocalStack. +We will also learn about `lstk terraform`, part of the `lstk` CLI, that allows you to run Terraform locally against LocalStack. ## Prerequisites For this tutorial, you will need: -- [LocalStack for AWS](https://hub.docker.com/r/localstack/localstack) +- [LocalStack for AWS](https://www.localstack.cloud/localstack-for-aws) - [Terraform](https://www.terraform.io/downloads.html) -- [awslocal](https://github.com/localstack/awscli-local) +- [`lstk aws`](/aws/connecting/aws-cli#localstack-aws-cli-lstk-aws) ## Architecture @@ -97,16 +97,16 @@ Create a file named `error.html` next to `index.html` inside `www/` and add the S3 will return the above file content only for HTTP 4XX error codes. Some browsers might choose to display their custom error message if a user tries to access a resource that does not exist. In this case, browsers might ignore the above error document. -With the initial setup complete, we can now move on to creating a static website using S3 via `awslocal`, LocalStack's wrapper for the AWS CLI. +With the initial setup complete, we can now move on to creating a static website using S3 via `lstk aws`, LocalStack's wrapper for the AWS CLI. ## Hosting a static website using S3 To create a static website using S3, we need to create a bucket, enable static website hosting, and upload the files to the bucket. -We will use the `awslocal` CLI for these operations. +We will use the `lstk aws` CLI for these operations. Navigate to the root directory of the project and create a bucket named `testwebsite` using LocalStack's S3 API: ```bash -awslocal s3api create-bucket --bucket testwebsite +lstk aws s3api create-bucket --bucket testwebsite ``` With the bucket created, we can now attach a policy to it to allow public access and its contents. @@ -130,19 +130,19 @@ Let's create a file named `bucket_policy.json` in the project root (next to the Let's now attach the policy to the bucket: ```bash -awslocal s3api put-bucket-policy --bucket testwebsite --policy file://bucket_policy.json +lstk aws s3api put-bucket-policy --bucket testwebsite --policy file://bucket_policy.json ``` With the policy attached, we can now sync the contents of our `www/` directory to the bucket: ```bash -awslocal s3 sync ./www/ s3://testwebsite +lstk aws s3 sync ./www/ s3://testwebsite ``` We'll now enable static website hosting on the bucket and configure the index and error documents: ```bash -awslocal s3 website s3://testwebsite/ --index-document index.html --error-document error.html +lstk aws s3 website s3://testwebsite/ --index-document index.html --error-document error.html ``` If you are deploying a static website using S3 on real AWS cloud, your S3 website endpoint will follow one of these two formats: @@ -366,19 +366,19 @@ name = "testwebsite" website_endpoint = "http://testwebsite.s3-website.localhost.localstack.cloud:4566" ``` -In the above command, we specified `testwebsite` as the bucket name to keep it consistent with the `awslocal` flow above and the testing commands further down. +In the above command, we specified `testwebsite` as the bucket name to keep it consistent with the `lstk aws` flow above and the testing commands further down. You can specify any bucket name since LocalStack is ephemeral, and stopping your LocalStack container will delete all the created resources. The above command output includes the ARN, name, LocalStack website domain, and the website endpoint URL of the bucket. You can navigate directly to the printed `website_endpoint` to view your site, since the endpoint uses `localhost.localstack.cloud`, no real AWS resources have been created. -You can optionally use the `tflocal` CLI as a drop-in replacement for the official Terraform CLI. `tflocal` uses the Terraform Override mechanism to create a temporary `localstack_providers_override.tf` file, which is deleted after the infrastructure is created. +You can optionally use the `lstk terraform` command as a drop-in replacement for the official Terraform CLI. `lstk terraform` uses the Terraform Override mechanism to create a temporary `localstack_providers_override.tf` file, which is deleted after the infrastructure is created. It mitigates the need to create the `provider.tf` file manually. -You can use `tflocal` to create the infrastructure by running the following commands: +You can use `lstk terraform` to create the infrastructure by running the following commands: ```bash -tflocal init -tflocal plan -tflocal apply +lstk terraform init +lstk terraform plan +lstk terraform apply ``` ## Testing the application @@ -418,10 +418,10 @@ You should receive the content from your `error.html` file: "Something is amiss. ### Checking bucket configuration -You can verify the bucket's website configuration using `awslocal`: +You can verify the bucket's website configuration using `lstk aws`: ```bash -awslocal s3api get-bucket-website --bucket testwebsite +lstk aws s3api get-bucket-website --bucket testwebsite ``` This command should return the index and error document configuration for your bucket. @@ -431,7 +431,7 @@ This command should return the index and error document configuration for your b To confirm all your files were uploaded correctly: ```bash -awslocal s3 ls s3://testwebsite/ +lstk aws s3 ls s3://testwebsite/ ``` This will display all the files in your bucket, including `index.html`, `error.html`, and any additional assets. diff --git a/src/content/docs/aws/tutorials/schema-evolution-glue-msk.mdx b/src/content/docs/aws/tutorials/schema-evolution-glue-msk.mdx index c6881a84b..becec57c6 100644 --- a/src/content/docs/aws/tutorials/schema-evolution-glue-msk.mdx +++ b/src/content/docs/aws/tutorials/schema-evolution-glue-msk.mdx @@ -53,7 +53,7 @@ For this tutorial you will need: - [LocalStack for AWS](https://localstack.cloud/pricing/) to emulate Amazon MSK and AWS Glue Schema Registry locally - Don't worry, if you don't have a subscription yet, you can just get a trial license for free. -- [awslocal](/aws/connecting/aws-cli#localstack-aws-cli-awslocal) +- [`lstk aws`](/aws/connecting/aws-cli#localstack-aws-cli-lstk-aws) - Java 11+ - Maven 3 @@ -590,13 +590,13 @@ Now that the initial coding is done, we can give it a try. Let's start LocalStack: ```bash -LOCALSTACK_AUTH_TOKEN= localstack start -d +lstk start ``` -Once LocalStack is started, we can create a new Kafka cluster using `awslocal`: +Once LocalStack is started, we can create a new Kafka cluster using `lstk aws`: ```bash -awslocal kafka create-cluster \ +lstk aws kafka create-cluster \ --cluster-name "unicorn-ride-cluster" \ --kafka-version "2.2.1" \ --number-of-broker-nodes 1 \ @@ -618,7 +618,7 @@ It takes some time for the cluster to get up and running. We can monitor the state with `describe-cluster`: ```bash -awslocal kafka describe-cluster --cluster-arn "arn:aws:kafka:us-east-1:000000000000:cluster/unicorn-ride-cluster/f9b16124-baf3-459b-8507-ec6c605b7a0a-25" +lstk aws kafka describe-cluster --cluster-arn "arn:aws:kafka:us-east-1:000000000000:cluster/unicorn-ride-cluster/f9b16124-baf3-459b-8507-ec6c605b7a0a-25" ``` ```bash title="Output" @@ -646,7 +646,7 @@ Once the `State` is `ACTIVE`, the cluster is ready to be used. Now it's time to create our Glue Schema Registry: ```bash -awslocal glue create-registry --registry-name unicorn-ride-request-registry +lstk aws glue create-registry --registry-name unicorn-ride-request-registry ``` ```bash title="Output" @@ -659,7 +659,7 @@ awslocal glue create-registry --registry-name unicorn-ride-request-registry In the newly created registry, we can now add our initial `UnicornRideRequest` schema: ```bash -awslocal glue create-schema \ +lstk aws glue create-schema \ --registry-id RegistryName="unicorn-ride-request-registry" \ --schema-name unicorn-ride-request-schema-avro \ --compatibility BACKWARD \ @@ -697,7 +697,7 @@ Finally, everything is ready to start our `Producer` and `Consumer`. First, we need to get the bootstrap server address from the Kafka cluster: ```bash -awslocal kafka get-bootstrap-brokers --cluster-arn "arn:aws:kafka:us-east-1:000000000000:cluster/unicorn-ride-cluster/f9b16124-baf3-459b-8507-ec6c605b7a0a-25" +lstk aws kafka get-bootstrap-brokers --cluster-arn "arn:aws:kafka:us-east-1:000000000000:cluster/unicorn-ride-cluster/f9b16124-baf3-459b-8507-ec6c605b7a0a-25" ``` ```bash title="Output" @@ -1051,122 +1051,7 @@ Our new consumer, based on the latest version of the schema, will be able to suc ```bash mvn -pl consumer-2 exec:java -Dexec.args="--bootstrap-servers localhost:4511" ``` -## Testing the application -After deploying and running the example, you can verify that your MSK and Glue Schema Registry integration is functioning correctly. -This section consolidates the end-to-end verification steps — producing and consuming messages, and validating schema compatibility. - ---- - -### 1. Produce a message to the Kafka topic - -Use the `awslocal` CLI or your preferred Kafka client to produce a test message using the initial Avro schema: - -```bash -awslocal kafka-produce \ - --topic my-topic \ - --value '{"name": "Alice", "age": 30}' -``` -Expected output: - -Message successfully produced to topic 'my-topic' - - -This message is serialized using the Avro schema registered in the Glue Schema Registry. - -### 2. Consume and verify the message - -Consume from the same topic using a compatible schema: -``` -awslocal kafka-consume \ - --topic my-topic \ - --from-beginning \ - --max-messages 1 -``` - -Expected output: -``` -{"name": "Alice", "age": 30} -``` - -This confirms that your consumer can successfully deserialize messages using the registered schema version. - -### 3. Test schema evolution and compatibility - -Now modify your Avro schema to simulate an update (for example, adding a new optional field): -``` -{ - "type": "record", - "name": "User", - "fields": [ - { "name": "name", "type": "string" }, - { "name": "age", "type": "int" }, - { "name": "email", "type": ["null", "string"], "default": null } - ] -} -``` -Register the updated schema version: -``` -awslocal glue register-schema-version \ - --schema-id SchemaName=my-schema \ - --schema-definition file://updated_user_schema.avsc -``` -Expected output: -``` -{ - "SchemaVersionId": "abcd1234...", - "Status": "AVAILABLE" -} -``` -Then verify schema compatibility: -``` -awslocal glue check-schema-compatibility \ - --schema-id SchemaName=my-schema \ - --data-format AVRO \ - --schema-definition file://updated_user_schema.avsc -``` -Expected output: -``` -{ - "Compatibility": "COMPATIBLE" -} -``` -This indicates that the updated schema maintains backward compatibility with existing data. - -4. Validate end-to-end flow after schema update - -Produce a message using the new schema: -``` -awslocal kafka-produce \ - --topic my-topic \ - --value '{"name": "Bob", "age": 25, "email": "bob@example.com"}' -``` - -Then consume again to verify successful deserialization: -``` -awslocal kafka-consume \ - --topic my-topic \ - --from-beginning \ - --max-messages 2 -``` - -Expected output: -``` -{"name": "Alice", "age": 30} -{"name": "Bob", "age": 25, "email": "bob@example.com"} -``` - -Both messages deserialize successfully, confirming that schema evolution and compatibility are functioning as expected. - -### 5. Summary - -You’ve validated that: - -* Kafka topics in LocalStack correctly trigger message serialization/deserialization through Glue Schema Registry. - -* Schema evolution (adding optional fields) preserves backward compatibility. - -* Both producer and consumer integrate seamlessly after schema updates. ## Conclusion Apache Kafka is used as the core messaging system in complex environments, with independent producers and consumers. diff --git a/src/content/docs/aws/tutorials/serverless-quiz-app.mdx b/src/content/docs/aws/tutorials/serverless-quiz-app.mdx index 0b6f91f31..da52497b3 100644 --- a/src/content/docs/aws/tutorials/serverless-quiz-app.mdx +++ b/src/content/docs/aws/tutorials/serverless-quiz-app.mdx @@ -30,8 +30,8 @@ Using LocalStack, we can develop and test this entire serverless infrastructure For this tutorial, you will need: - [LocalStack for AWS](https://localstack.cloud/pricing/) with a valid auth token -- [AWS CLI](https://docs.localstack.cloud/user-guide/integrations/aws-cli/) with [`awslocal` wrapper](https://docs.localstack.cloud/user-guide/integrations/aws-cli/#localstack-aws-cli-awslocal) -- [AWS CDK](https://docs.localstack.cloud/user-guide/integrations/aws-cdk/) with [`cdklocal` wrapper](https://github.com/localstack/aws-cdk-local) (**optional**) +- [AWS CLI](https://docs.localstack.cloud/user-guide/integrations/aws-cli/) with [`lstk aws`](/aws/connecting/aws-cli#localstack-aws-cli-lstk-aws) +- [AWS CDK](https://docs.localstack.cloud/user-guide/integrations/aws-cdk/) with [`lstk cdk`](/aws/connecting/infrastructure-as-code/aws-cdk#aws-cdk-cli-for-localstack) (**optional**) - [Python 3.11+](https://www.python.org/downloads/) and `pip` - [curl](https://curl.se/) for testing API endpoints - [`make`](https://www.gnu.org/software/make/) (**optional**, but recommended for running the sample application) @@ -90,8 +90,7 @@ pip install -r tests/requirements-dev.txt First, start LocalStack with your auth token: ```bash -localstack auth set-token -localstack start +lstk start ``` ### Deploy the Infrastructure @@ -112,8 +111,8 @@ Alternatively, deploy using AWS CDK with LocalStack: ```bash cd cdk -cdklocal bootstrap -AWS_CMD=awslocal CDK_CMD=cdklocal bash ../bin/deploy_cdk.sh +lstk cdk bootstrap +AWS_CMD="lstk aws" CDK_CMD="lstk cdk" bash bin/deploy_cdk.sh ``` Both deployment methods will: @@ -150,6 +149,9 @@ Navigate to the CloudFront URL from the deployment output to interact with the q Run the complete test suite to validate quiz creation, submission, and scoring: ```bash +export AWS_DEFAULT_REGION=us-east-1 +export AWS_ACCESS_KEY_ID=test +export AWS_SECRET_ACCESS_KEY=test pytest tests/test_infra.py ``` @@ -170,8 +172,8 @@ Use the LocalStack Web Application to inspect your deployed resources: Skip the deployment step by loading a pre-configured environment: ```bash -localstack restart -localstack pod load serverless-quiz-app +lstk restart +lstk snapshot load pod:serverless-quiz-app ``` This instantly loads the complete application infrastructure from a saved state. diff --git a/src/content/docs/aws/tutorials/simulating-outages.mdx b/src/content/docs/aws/tutorials/simulating-outages.mdx index bf2274ec0..bd809c89a 100644 --- a/src/content/docs/aws/tutorials/simulating-outages.mdx +++ b/src/content/docs/aws/tutorials/simulating-outages.mdx @@ -25,11 +25,11 @@ Chaos API offers a means to deliberately introduce failures and observe their im In this tutorial we study the effects of outages on a sample AWS application. We use the Chaos API to simulate the outage and design a mitigation to make the application resilient against database outages. -This tutorial is designed for users new to the Chaos API and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This tutorial is designed for users new to the Chaos API and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/connecting/aws-cli#localstack-aws-cli-lstk-aws) command. In this example, we will use the Chaos API to create controlled outages in a DynamoDB database. The aim is to test the software's behavior and error handling capabilities. -For this particular example, we'll be using a [sample application repository](https://github.com/localstack-samples/samples-chaos-engineering/tree/master/chaos-api). +For this particular example, we'll be using a [sample application repository](https://github.com/localstack-samples/sample-chaos-api-serverless). Clone the repository, and follow the instructions below to get started. ### Prerequisites @@ -37,7 +37,7 @@ Clone the repository, and follow the instructions below to get started. The general prerequisites for this guide are: - LocalStack for AWS with [LocalStack Auth Token](/aws/getting-started/auth-token) -- [AWS CLI](/aws/connecting/aws-cli) with the [`awslocal` wrapper](/aws/connecting/aws-cli#localstack-aws-cli-awslocal) +- [AWS CLI](/aws/connecting/aws-cli) with the [`lstk aws`](/aws/connecting/aws-cli#localstack-aws-cli-lstk-aws) command - [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) Start LocalStack by using the `docker-compose.yml` file from the repository. @@ -49,6 +49,12 @@ LOCALSTACK_AUTH_TOKEN= docker compose up ``` +Given that you've started LocalStack via `docker-compose`, you'll need to configure the `lstk` CLI to contact your container: + +```bash +export LSTK_ENDPOINT_URL=http://localhost.localstack.cloud:4566 +``` + ### Architecture The following diagram shows the architecture that this application builds and deploys: @@ -80,7 +86,7 @@ Product added/updated successfully. After ending the outage, confirm that previously failed items are stored successfully: ```bash -awslocal dynamodb scan --table-name Products +lstk aws dynamodb scan --table-name Products ``` Expected output: @@ -184,7 +190,7 @@ With the outage now ended, the Product that initially failed to reach the databa This can be confirmed by scanning the database. ```bash -awslocal dynamodb scan --table-name Products +lstk aws dynamodb scan --table-name Products ``` ```bash title="Output" diff --git a/src/content/docs/aws/tutorials/terraform-shipment-app-guide.mdx b/src/content/docs/aws/tutorials/terraform-shipment-app-guide.mdx index 08ef749ee..221f4fef7 100644 --- a/src/content/docs/aws/tutorials/terraform-shipment-app-guide.mdx +++ b/src/content/docs/aws/tutorials/terraform-shipment-app-guide.mdx @@ -26,9 +26,9 @@ This sample app consists of a React frontend and a Spring Boot backend, integrat Make sure the following tools and dependencies are installed and configured on your local machine before proceeding: -- **LocalStack** (preferably Team or Pro edition for advanced features) +- **LocalStack for AWS** - **Terraform CLI** -- **AWS CLI** with the [awslocal](https://docs.localstack.cloud/aws/connecting/aws-cli/#localstack-aws-cli-awslocal) wrapper for LocalStack +- **AWS CLI** with the [`lstk aws`](https://docs.localstack.cloud/aws/connecting/aws-cli/#localstack-aws-cli-lstk-aws) command for LocalStack - **Maven 3.8.5+** and **Java 17** for Spring Boot backend - **Node.js** and **npm** for React frontend - **make** (optional, but recommended for simplified commands) @@ -51,8 +51,7 @@ This command builds the Lambda validator JAR and installs frontend Node.js packa Start LocalStack in the background with your authorization token configured: ``` -localstack auth set-token -localstack start -d +lstk start ``` Use the provided Makefile to deploy all infrastructure components: @@ -115,7 +114,7 @@ This project illustrates: - Reactive messaging using SNS and SQS. - Seamless switching between AWS and LocalStack via Spring Profiles. - Integration testing using Testcontainers. -- Using LocalStack CLI wrappers (`awslocal`, `tflocal`) for streamlined local development. +- Using LocalStack's `lstk aws` and `lstk terraform` commands for streamlined local development. - Infrastructure as Code testing enabling consistent, repeatable environment setups. diff --git a/src/content/docs/aws/tutorials/using-terraform-with-testcontainers-and-localstack.mdx b/src/content/docs/aws/tutorials/using-terraform-with-testcontainers-and-localstack.mdx index 8cffa603c..80e9e72cf 100644 --- a/src/content/docs/aws/tutorials/using-terraform-with-testcontainers-and-localstack.mdx +++ b/src/content/docs/aws/tutorials/using-terraform-with-testcontainers-and-localstack.mdx @@ -40,11 +40,11 @@ For this tutorial, you will need: - [LocalStack for AWS](/aws/getting-started/auth-token) to emulate the AWS services and to use LocalStack Extensions. If you don't have LocalStack for AWS yet, you can sign up on our [webapp](https://app.localstack.cloud) to get a trial license for free. - [Docker](https://docker.io/) -- [LocalStack CLI](/aws/getting-started/installation) +- [`lstk`](/aws/getting-started/installation#lstk) - [AWS CLI](https://aws.amazon.com/cli/) - Optional for building the Lambda functions: [Java 17](https://openjdk.org/install/) - Optional for building the Lambda functions: [Apache Maven 3.9.8](https://maven.apache.org/install.html) -- Optional: [Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) and [tflocal](https://github.com/localstack/terraform-local) +- Optional: [Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) and [`lstk terraform`](/aws/connecting/infrastructure-as-code/terraform#lstk-terraform) ## Project overview @@ -71,24 +71,66 @@ on their official documentation page. #### LocalStack CLI -In the root folder of the demo project run: +`lstk` takes container environment variables and bind mounts from its [`config.toml`](/aws/developer-tools/running-localstack/lstk/#configuration) +rather than from command-line flags. +In the root folder of the demo project, create a project-local `.lstk/config.toml`: + +```toml title=".lstk/config.toml" +[[containers]] +type = "aws" +tag = "latest" +port = "4566" +env = ["terraform-init"] +volumes = [ + "../terraform:/etc/localstack/init/ready.d", +] + +[env.terraform-init] +EXTENSION_AUTO_INSTALL = "localstack-extension-terraform-init" +``` + +:::note +Relative host paths in `volumes` are resolved against the directory that holds `config.toml` — here `.lstk/` — which is why the mount is written as `../terraform` rather than `./terraform`. +::: + +`main.tf` refers to the Lambda JAR as `target/product-lambda.jar`, relative to the Terraform working directory. +Build it and stage it inside `terraform/`, so that the single mount above carries both the configuration and the JAR into the container: + +```bash +mvn clean package -DskipTests +mkdir -p terraform/target +cp target/product-lambda.jar terraform/target/product-lambda.jar +``` + +Then start LocalStack from the project root: ```bash -export LOCALSTACK_AUTH_TOKEN= -localstack start -e EXTENSION_AUTO_INSTALL=localstack-extension-terraform-init \ - -v ./terraform/main.tf:/etc/localstack/init/ +lstk start ``` This is the easiest way to quickly spin up the desired services at startup. -The command starts LocalStack with the configuration to automatically install the **`localstack-extension-terraform-init`** [extension](/aws/customization/integrations/extensions/) and -mount the necessary files into the container: the Terraform configuration file and the Lambda JAR file. +The [`env` profile](/aws/developer-tools/running-localstack/lstk/#passing-environment-variables-to-the-container) tells LocalStack to automatically install the **`localstack-extension-terraform-init`** [extension](/aws/customization/integrations/extensions/), and +the [`volumes` entry](/aws/developer-tools/running-localstack/lstk/#volume-mounts) mounts the Terraform configuration and the Lambda JAR into the container. The extension will install both `terraform` and `tflocal` into your LocalStack container, and enable the init hook runners to detect Terraform files. You can also organize your Terraform files into subdirectories if you want. -If Docker gives you any trouble regarding mounting permissions, you can add `$(pwd)` in front of the local paths, to turn them into -absolute paths. +Since the initialization hook runs `terraform init`, the AWS Terraform provider would be downloaded in the container on every start. Mounting the whole `terraform` directory, as above, avoids this: any Terraform state including the `.terraform` folder that contains the provider will be cached on your host directory, however it may require `sudo` permissions to modify or delete, as it is created by the container. -Since the initialization hook runs `terraform init`, the AWS Terraform provider will be downloaded in the container every time. You can avoid this by mounting a directory instead of a single file. Any Terraform state including the `.terraform` folder that contains the provider, will be cached on your host directory, however they may require `sudo` permissions to modify or delete, as they are created by the container. +Once the `Ready.` message appears, you can list what the init hook created: + +```bash +lstk status +``` + +```bash title="Output" +~ 5 resources · 4 services + SERVICE RESOURCE REGION ACCOUNT + ApiGateway nq7sycvcbw us-east-1 000000000000 + DynamoDB Products us-east-1 000000000000 + IAM productRole global 000000000000 + Lambda add-product us-east-1 000000000000 + Lambda get-product us-east-1 000000000000 +``` #### Docker compose @@ -132,12 +174,17 @@ Volumes: After running `docker compose up`, we should keep an eye on the container logs until the `Ready.` message appears. +Given that you've started LocalStack via `docker-compose`, you'll need to configure the `lstk` CLI to contact your container: + +```bash +export LSTK_ENDPOINT_URL=http://localhost.localstack.cloud:4566 +``` + Now we can test the functionality of our stack by running the following commands: ```bash -aws apigateway get-rest-apis \ - --query 'items[?name==`product-api-gateway`].id' \ - --endpoint http://localhost.localstack.cloud:4566 +lstk aws apigateway get-rest-apis \ + --query 'items[?name==`product-api-gateway`].id' ``` ```bash title="Output"