diff --git a/content/en/references/credentials.md b/content/en/references/credentials.md index d27b7f1353..3e053e4f39 100644 --- a/content/en/references/credentials.md +++ b/content/en/references/credentials.md @@ -6,18 +6,20 @@ description: > Credentials for accessing LocalStack AWS API --- -Like AWS, LocalStack requires access key IDs to be set in all operations. -The choice of access key ID will affect [multi-account namespacing]({{< ref "multi-account-setups" >}}). -Values of secret access keys are currently ignored by LocalStack. +Like AWS, LocalStack requires AWS credentials to be supplied in all API operations. + +## Access Key ID + +For root accounts, the choice of access key ID affects [multi-account namespacing]({{< ref "multi-account-setups" >}}). Access key IDs can be one of following patterns: -## Accounts IDs +### Accounts IDs You can specify a 12-digit number which will be taken by LocalStack as the account ID. For example, `112233445566`. -## Structured access key ID +### Structured access key ID You can specify a structured key like `LSIAQAAAAAAVNCBMPNSG` (which translates to account ID `000000000042`). This must be at least 20 characters in length and must be decodable to an account ID. @@ -34,7 +36,13 @@ We strongly recommend leaving it on. Please refer to the [IAM docs]({{< ref "user-guide/aws/iam" >}}) to learn how to create access keys in LocalStack. -## Alphanumeric string +### Alphanumeric string You can also specify an arbitrary alphanumeric access key ID like `test` or `foobar123`. -In all such cases, the account ID will be evaluated to `000000000000`. +In all such cases, the account ID is evaluated to `000000000000`. + +## Secret Access Key + +The value of the secret access key are currently ignored by LocalStack. + +We recommend using the same value as access key ID or `test` diff --git a/content/en/references/init-hooks.md b/content/en/references/init-hooks.md index 93a4695d0d..e79e727e7b 100644 --- a/content/en/references/init-hooks.md +++ b/content/en/references/init-hooks.md @@ -7,7 +7,7 @@ aliases: - /localstack/init-hooks/ --- -## Lifecycle stages and hooks +## Lifecycle Stages and Hooks LocalStack has four well-known lifecycle phases or stages: * `BOOT`: the container is running but the LocalStack runtime has not been started @@ -41,14 +41,14 @@ A script can be in one of four states: `UNKNOWN`, `RUNNING`, `SUCCESSFUL`, `ERRO Scripts are by default in the `UNKNOWN` state once they have been discovered. The remaining states should be self-explanatory. -### Execution order and script failures +### Execution Order and Script Failures Scripts are sorted and executed in alphanumerical order. If you use subdirectories, scripts in parent folders are executed first, and then the directories are traversed in alphabetical order, depth first. If an init script fails, the remaining scripts will still be executed in order. A script is considered in `ERROR` state if it is a shell script and returns with a non-zero exit code, or if a Python script raises an exception during its execution. -## Status endpoint +## Status Endpoint There is an additional endpoint at `localhost:4566/_localstack/init` which returns the state of the initialization procedure. Boot scripts (scripts placed in `boot.d`) are currently always in the `UNKNOWN` state, since they are executed outside the LocalStack process and we don't know whether they have been successfully executed or not. @@ -80,7 +80,7 @@ curl -s localhost:4566/_localstack/init | jq . } ``` -### Query individual stages +### Querying Stages You can also query a specific stage at `localhost:4566/_localstack/init/`: @@ -109,12 +109,14 @@ curl -s localhost:4566/_localstack/init/ready | jq .completed which returns either `true` or `false`. -## Usage example +## Example A common use case for init hooks is pre-seeding LocalStack with custom state. -If you have more complex state, [Cloud Pods]({{< ref "user-guide/state-management/cloud-pods" >}}) and [how to auto-load them on startup]({{< ref "user-guide/state-management/cloud-pods#auto-loading-cloud-pods" >}}) may be a good option to look into! +For example if you want to have a certain S3 bucket or DynamoDB table created when starting LocalStack, init hooks can be very useful. -But for simple 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. +{{< callout "tip" >}} +If you have more complex states, [Cloud Pods]({{< ref "user-guide/state-management/cloud-pods" >}}) and [how to auto-load them on startup]({{< ref "user-guide/state-management/cloud-pods#auto-loading-cloud-pods" >}}) may be a good option to look into! +{{< /callout >}} 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/`. @@ -123,6 +125,9 @@ You can use anything available inside the container, including `awslocal`: ```bash #!/bin/bash + +export AWS_ACCESS_KEY_ID=000000000000 AWS_SECRET_ACCESS_KEY=000000000000 + awslocal s3 mb s3://my-bucket awslocal sqs create-queue --queue-name my-queue ``` @@ -155,24 +160,20 @@ DOCKER_FLAGS='-v /path/to/init-aws.sh:/etc/localstack/init/ready.d/init-aws.sh' Another use for init hooks can be seen when [adding custom TLS certificates to LocalStack]({{< ref "custom-tls-certificates#custom-tls-certificates-with-init-hooks" >}}). -### Terraform configuration files as init hooks +### Terraform Files as Init Hooks Running Terraform configuration files as init hooks requires the installation of a special extension. For more information on how to manage [LocalStack extensions]({{< ref "user-guide/extensions/" >}}), please refer to the dedicated documentation page, and for more details on running init hooks in development mode, you can check out the [extension repository description](https://github.com/localstack/localstack-extensions/tree/main/terraform-init). -##### Usage - 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. -##### Example - -main.tf: - ```terraform +# main.tf + resource "aws_s3_bucket" "example" { bucket = "my-tf-test-bucket" @@ -183,7 +184,7 @@ Environment = "Dev" } ``` -Start LocalStack Pro with mounted main.tf: +Start LocalStack Pro with mounted `main.tf`: {{< tabpane >}} {{< tab header="docker-compose.yml" lang="yml" >}} @@ -252,3 +253,5 @@ If you are having issues with your initialization hooks not being executed, plea * If your script does not show up in the list of discovered init scripts, please check your Docker volume mount. Most likely the scripts are not properly mounted into the Docker container. +* Are resources not being created? + * Ensure that AWS [credentials]({{< ref "references/credentials" >}}) are set, e.g. through `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables.