Skip to content

AWS external secrets docs #1481

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jroper wants to merge 1 commit into
base: main
Choose a base branch
from
+202 −3
Open

AWS external secrets docs #1481

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
162 changes: 161 additions & 1 deletion docs/src/modules/operations/pages/projects/external-secrets.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,13 +38,171 @@ akka secret external delete <secret-name>
----
--

== AWS Secrets

Akka services running on AWS can access external secrets from AWS Secrets Manager and AWS Systems Manager Parameter Store.

=== Setting up

Before you set up AWS external secrets, you will need the following information:

* The account ID of your AWS account, which we will refer to in the scripts below using the environment variable `AWS_ACCOUNT_ID`.
* The region for your AWS account, which we will refer to in the scripts below using the environment variable `AWS_REGION`.
* The ID of the Akka project that you wish to access to the secrets, which we will refer to in the scripts below using the environment variable `AKKA_PROJECT_ID`. This is a UUID, and can be obtained using the `akka project get` command.
* The name of the service that you wish to access the secrets, which we will refer to in the scripts below using the environment variable `AKKA_SERVICE_NAME`.

The following script can set them:

[source, command window]
----
export AWS_ACCOUNT_ID=123456789012
export AWS_REGION=us-east-2
export AKKA_PROJECT_ID=bc16cf0c-909f-402d-bbb0-88ea1d582854
export AKKA_SERVICE_NAME=my-service
----

Now, you will need to determine the OIDC issuer for your region. This can be determined by running:

[source, command window]
----
akka secrets external info
----

If you only have one region, the above will give you some helpful snippets that may be used below. If you have more than one region, you can specify the region you want the info for using the `--region` flag.

Copy the issuer and place it in an environment variable called `AKKA_OIDC_ISSUER`, or if you only have a single region, you can do so using the following command:

[source, command window]
----
export AKKA_OIDC_ISSUER=$(akka secrets external info -o go-template='{{(index .Items 0).WorkloadIdentity.Aws.OidcIssuer}}'}
Copy link
Copy Markdown
Member

@janikdotzel janikdotzel Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

export AKKA_OIDC_ISSUER=$(akka secrets external info -o go-template='{{(index .Items 0).WorkloadIdentity.Aws.OidcIssuer}}'}

There's a } at the end. It should be a ) instead:

export AKKA_OIDC_ISSUER=$(akka secrets external info -o go-template='{{(index .Items 0).WorkloadIdentity.Aws.OidcIssuer}}')

----

AWS often refers to an OIDC provider via the issuer with the `https://` stripped off of it, so for convenience, we will also set that here:

[source, command window]
----
export AKKA_OIDC_PROVIDER=$(echo $AKKA_OIDC_ISSUER | sed -e "s/^https:\/\///")
----

Now create a secret that you want the service to access:

[source, command window]
----
aws --region "$AWS_REGION" secretsmanager create-secret --name my-secret \
--secret-string '{"username":"some-user", "password":"hunter2"}'
----

Now create a policy that allows access to the secret:

[source, command window]
----
POLICY_ARN=$(aws --region "$AWS_REGION" --query Policy.Arn --output text iam create-policy \
--policy-name akka-secret-access-policy --policy-document '{
"Version": "2012-10-17",
"Statement": [ {
"Effect": "Allow",
"Action": ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"],
"Resource": ["arn:*:secretsmanager:*:*:secret:my-secret-??????"]
} ]
}')
----

Now create a role that the Akka service will assume bound to the policy:

[source, command window]
----
TRUST_POLICY_JSON=$(cat <<EOF
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::$AWS_ACCOUNT_ID:oidc-provider/$AKKA_OIDC_PROVIDER"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"$AKKA_OIDC_PROVIDER:aud": "sts.amazonaws.com",
"$AKKA_OIDC_PROVIDER:sub": "system:serviceaccount:$AKKA_PROJECT_ID:klx-$AKKA_SERVICE_NAME"
}
}
}
]
}
EOF
)

aws iam create-role --role-name akka-service-role --assume-role-policy-document "$TRUST_POLICY_JSON" \
--description "My Akka service role"

aws iam attach-role-policy --role-name akka-service-role \
--policy-arn=arn:aws:iam::$AWS_ACCOUNT_ID:policy/akka-secret-access-policy
----

Note the `klx-` prefix before the service name in the OIDC provider subject.

Finally, we can tell Akka to assume this role for your service:

[source, command window]
----
akka service deploy $AKKA_SERVICE_NAME
Copy link
Copy Markdown
Member

@janikdotzel janikdotzel Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we add a \ at the end of the first line. My Shell executed akka service deploy $AKKA_SERVICE_NAME alone, then failed on the second line.

--aws-workload-identity-role-arn arn:aws:iam::$AWS_ACCOUNT_ID:role/akka-service-role
----

=== Managing AWS secrets using the project descriptor

The best way to manage AWS secrets is using the project descriptor. Please refer to xref:reference:descriptors/project-descriptor.adoc[] for details.

=== Adding AWS secrets with the CLI

To add AWS secrets to your Akka project, you can use the Akka CLI.

[.tabset]
--
CLI::
+
Use the `akka secret external aws create` command.
Copy link
Copy Markdown
Member

@janikdotzel janikdotzel Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR uses:

  • akka secret external aws create
  • akka secret external aws update

The CLI reference (akka_secrets_external_create_aws.adoc) documents:

  • akka secrets external create aws
  • akka secrets external update aws

+
[source, command line]
----
akka secret external aws create my-external-secret \ <1>
--object-name arn:aws:secretsmanager::$AWS_ACCOUNT_ID:secret:my-secret-QNTAHI \ <2>
Copy link
Copy Markdown
Member

@janikdotzel janikdotzel Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

--object-name arn:aws:secretsmanager::$AWS_ACCOUNT_ID:secret:my-secret-QNTAHI

Secrets Manager is a regional service.
ARNs include the region: arn:aws:secretsmanager:REGION:ACCOUNT_ID:secret:NAME. The region field is empty here. Should likely be:

--object-name arn:aws:secretsmanager:$AWS_REGION:$AWS_ACCOUNT_ID:secret:my-secret-QNTAHI

--object-alias some-file-name <3>
----
+
<1> External secret name
<2> The ARN of the secret
<3> The name of the file to mount the secret as
--

Adding multiple objects can be done by updating the secret after initial creation.

=== Updating AWS secrets

[.tabset]
--
CLI::
+
Use the `akka secret external aws update` command.
+
[source, command line]
----
akka secret external aws update my-external-secret \
--object-name arn:aws:secretsmanager::$AWS_ACCOUNT_ID:secret:some-other-secret-ENTHOI \
--object-alias some-other-file-name
----
--

When updating, if the passed in object name exists, the object will be updated, otherwise a new object will be added to the secret.

== Azure KeyVault

Akka services running on Azure can access external secrets from Azure KeyVault.

=== Setting up

Before you setting up Azure KeyVault, you will need the following information:
Before you set up Azure KeyVault, you will need the following information:

* The name of the Azure KeyVault that you wish to access, which we will refer to in the scripts below using the environment variable `KEYVAULT_NAME`.
* The ID of the Akka project that you wish to access to the secrets, which we will refer to in the scripts below using the environment variable `AKKA_PROJECT_ID`. This is a UUID, and can be obtained using the `akka project get` command.
Expand All @@ -66,6 +224,8 @@ Now, you will need to determine the OIDC issuer for your region. This can be det
akka secrets external info
----

If you only have one region, the above will give you some helpful snippets that may be used below. If you have more than one region, you can specify the region you want the info for using the `--region` flag.

Copy the issuer and place it in an environment variable called `AKKA_OIDC_ISSUER`, or if you only have a single region, you can do so using the following command:

[source, command window]
Expand Down
43 changes: 41 additions & 2 deletions docs/src/modules/reference/pages/descriptors/external-secret-descriptor.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,52 @@

[cols="1,1,1"]
|===
|Field |Type |Description
|Field |Type |Description

|*aws* |<<AwsExternalSecret>> |Configuration for AWS external secrets.
|*azure* |<<AzureExternalSecret>> |Configuration for Azure KeyVault external secrets.
|*gcp* |<<GcpExternalSecret>> |Configuration for GCP Secret Manager external secrets.
|===

=== AwsExternalSecret

AWS external secret configuration.

[cols="1,1,1"]
|===
|Field |Type |Description

|*objects* |[]<<AwsExternalSecretObject>> _required_ |The secret objects to mount from AWS.
|===

=== AwsExternalSecretObject

An AWS secret object that should be mounted as part of the external secret.

[cols="1,1,1"]
|===
|Field |Type |Description

|*name* |string _required_ |The name of the object. For Secrets Manager this is the SecretId parameter and can either be the friendly name or full ARN of the secret. For SSM Parameter Store, this is the name of the parameter and can be either the name or full ARN of the parameter.
|*type* |string |The ID of the tenant that the KeyVault is in. Optional if an ARN was specified in name, required otherwise.
Copy link
Copy Markdown
Member

@janikdotzel janikdotzel Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could this be a copy-paste mistake?

The ID of the tenant that the KeyVault is in.

After checking the akka_secrets_external_create_aws.adoc file, I'd recommend replacing it with something like

The type of the object, either secretsmanager or ssmparameter.

|*alias* |string |The filename of the object on disk, defaults to the object name.
|*version* |string |The version of the object, defaults to latest.
|*versionLabel* |string |The label of the version, defaults to latest.

Check failure on line 41 in docs/src/modules/reference/pages/descriptors/external-secret-descriptor.adoc

View workflow job for this annotation

GitHub Actions / Vale style checking 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'versionLabel'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'versionLabel'?", "location": {"path": "docs/src/modules/reference/pages/descriptors/external-secret-descriptor.adoc", "range": {"start": {"line": 41, "column": 3}}}, "severity": "ERROR"}
|*jmesPath* |[]<<AwsExternalSecretJmesPath>> |If the secret is JSON, specifies what JSON key value pairs to extract from the secret and mount as individual secrets.

Check failure on line 42 in docs/src/modules/reference/pages/descriptors/external-secret-descriptor.adoc

View workflow job for this annotation

GitHub Actions / Vale style checking 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'jmesPath'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'jmesPath'?", "location": {"path": "docs/src/modules/reference/pages/descriptors/external-secret-descriptor.adoc", "range": {"start": {"line": 42, "column": 3}}}, "severity": "ERROR"}
|*filePermission* |int |The permission of the file being mounted. Defaults to 0644. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. Note that YAML accepts both octal and decimal values, with octal values being specified by using a leading 0. Meanwhile JSON requires decimal values. If not specified, the volume's default mode will be used.
|===

=== AwsExternalSecretJmesPath

[cols="1,1,1"]
|===
|Field |Type |Description

|*path* |string _required_ |JMES path to use for extracting the secret.
|*alias* |string |The filename for the extracted secret.
|*filePermission* |int |The permission of the file being mounted. Defaults to 0644. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. Note that YAML accepts both octal and decimal values, with octal values being specified by using a leading 0. Meanwhile JSON requires decimal values. If not specified, the volume's default mode will be used.
|===

=== AzureExternalSecret

Azure KeyVault external secret configuration.
Expand All @@ -27,7 +67,6 @@
|*clientID* |string _required_ |The ID of the client that was created to access the KeyVault via federated workload identity.
|*cloudName* |string |If using a non default cloud, the name of the cloud.
|*objects* |[]<<AzureExternalSecretObject>> _required_ |The secret objects to mount from the KeyVault.

|===

=== AzureExternalSecretObject
Expand Down
Loading