Skip to content

Commit d558403

Browse files
kcbimontekcbimonte
committed
docx: all creds besides k8s
Signed-off-by: Kevin Bimonte <kbimonte@gmail.com>
1 parent 5dddd5a commit d558403

File tree

8 files changed

+895
-4
lines changed

8 files changed

+895
-4
lines changed

‎base.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ markdown_extensions:
1010
- admonition
1111
- def_list
1212
- tables
13+
- footnotes
1314
- attr_list
1415
- md_in_html
1516
- pymdownx.details

‎docs/docs/operation/creds/aws-secrets.md‎

Lines changed: 172 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,181 @@ title: The AWS Secrets Manager credential manager
44

55
## Configuration
66

7+
In order to integrate with AWS Secrets Manager for credential management, the web node must be configured with:
8+
9+
* an access key and secret key, or a session token
10+
* the AWS region that your parameters are stored within.
11+
12+
If no access key, secret key, or session token is provided, Concourse will attempt to use environment variables or the
13+
instance credentials assigned to the instance.
14+
15+
The web node's configuration specifies the following:
16+
17+
**`aws-secretsmanager-access-key`**: string
18+
19+
: A valid AWS access key.
20+
21+
: Environment variable `CONCOURSE_AWS_SECRETSMANAGER_ACCESS_KEY`.
22+
23+
**`aws-secretsmanager-secret-key`**: string
24+
25+
: The secret key that corresponds to the access key defined above.
26+
27+
: Environment variable `CONCOURSE_AWS_SECRETSMANAGER_SECRET_KEY`.
28+
29+
**`aws-secretsmanager-session-token`**: string
30+
31+
: A valid AWS session token.
32+
33+
: Environment variable `CONCOURSE_AWS_SECRETSMANAGER_SESSION_TOKEN`.
34+
35+
**`aws-secretsmanager-region`**: string
36+
37+
: The AWS region that requests to Secrets Manager will be sent to.
38+
39+
: Environment variable `CONCOURSE_AWS_SECRETSMANAGER_REGION`.
40+
41+
**`aws-secretsmanager-pipeline-secret-template`**: string
42+
43+
: The base path used when attempting to locate a pipeline-level secret.
44+
45+
: Environment variable `CONCOURSE_AWS_SECRETSMANAGER_PIPELINE_SECRET_TEMPLATE`.
46+
47+
: !!! example
48+
49+
Default: `/concourse/{{.Team}}/{{.Pipeline}}/{{.Secret}}`
50+
51+
**`aws-secretsmanager-team-secret-template`**: string
52+
53+
: The base path used when attempting to locate a team-level secret.
54+
55+
: Environment variable `CONCOURSE_AWS_SECRETSMANAGER_TEAM_SECRET_TEMPLATE`.
56+
57+
: !!! example
58+
59+
Default: `/concourse/{{.Team}}/{{.Secret}}`
60+
61+
For example, to launch the ATC and enable Secrets Manager, you may configure:
62+
63+
```shell
64+
concourse web ... \
65+
--aws-secretsmanager-region us-east-1 \
66+
--aws-secretsmanager-access-key AKIAIOSFODNN7EXAMPLE \
67+
--aws-secretsmanager-secret-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
68+
69+
# or use env variables
70+
CONCOURSE_AWS_SECRETSMANAGER_REGION="us-east-1" \
71+
CONCOURSE_AWS_SECRETSMANAGER_ACCESS_KEY="AKIAIOSFODNN7EXAMPLE" \
72+
CONCOURSE_AWS_SECRETSMANAGER_SECRET_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
73+
concourse web ...
74+
```
75+
76+
A more secure method is to configure
77+
an [IAM role](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) for your EC2 ATC
78+
instance so that credentials are fetched automatically from the EC2 metadata service.
79+
780
## Saving credentials in AWS
881

82+
It seems to be best to use the 'other type of secret' option and the 'plaintext' entry (otherwise your secrets will be
83+
interpolated as JSON) for best results. Make sure your secret locations match the lookup templates exactly; include the
84+
leading `/`, for example.
85+
986
## IAM Permissions
1087

88+
The following is an example of an IAM policy that can be used to grant permissions to an IAM user or instance role. Note
89+
that the `Resource` section can contain a wildcard to a secret or be restricted to an individual secret. In order for
90+
the health check to work properly (see [Scaling](#scaling)), Concourse needs to have access to
91+
the `__concourse-health-check` secret.
92+
93+
```json
94+
{
95+
"Version": "2012-10-17",
96+
"Statement": [
97+
{
98+
"Sid": "AllowAccessToSecretManagerParameters",
99+
"Effect": "Allow",
100+
"Action": [
101+
"secretsmanager:ListSecrets"
102+
],
103+
"Resource": "*"
104+
},
105+
{
106+
"Sid": "AllowAccessGetSecret",
107+
"Effect": "Allow",
108+
"Action": [
109+
"secretsmanager:GetSecretValue",
110+
"secretsmanager:DescribeSecret"
111+
],
112+
"Resource": [
113+
"arn:aws:secretsmanager:*:*:secret:/concourse/*",
114+
"arn:aws:secretsmanager:*:*:secret:__concourse-health-check-??????"
115+
]
116+
}
117+
]
118+
}
119+
```
120+
121+
If you wish to restrict concourse to only have access to secrets for a specific pipeline, you can
122+
replace `"arn:aws:secretsmanager:*:*:secret:/concourse/*"` in the example above with:
123+
124+
```json
125+
{
126+
"Version": "2012-10-17",
127+
"Statement": [
128+
{
129+
"Sid": "AllowAccessToSecretManagerParameters",
130+
"Effect": "Allow",
131+
"Action": [
132+
"secretsmanager:ListSecrets"
133+
],
134+
"Resource": "*"
135+
},
136+
{
137+
"Sid": "AllowAccessGetSecret",
138+
"Effect": "Allow",
139+
"Action": [
140+
"secretsmanager:GetSecretValue",
141+
"secretsmanager:DescribeSecret"
142+
],
143+
"Resource": [
144+
"arn:aws:secretsmanager:*:*:secret:/concourse/TEAM_NAME/*",
145+
"arn:aws:secretsmanager:*:*:secret:/concourse/TEAM_NAME/PIPELINE_NAME/*",
146+
"arn:aws:secretsmanager:*:*:secret:__concourse-health-check-??????"
147+
]
148+
}
149+
]
150+
}
151+
```
152+
153+
where `TEAM_NAME` and `PIPELINE_NAME` are replaced with the team and name of the pipeline in question.
154+
155+
For more information on how to use IAM roles to restrict access to Secrets Manager, review
156+
the [official documentation](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_identity-based-policies.html).
157+
11158
## Credential Lookup Rules
12159

13-
## Scaling
160+
When resolving a parameter such as `((foo_param))`, Concourse will look in the following paths, in order:
161+
162+
* `/concourse/TEAM_NAME/PIPELINE_NAME/foo_param`
163+
* `/concourse/TEAM_NAME/foo_param`
164+
165+
The leading `/concourse` can be changed by specifying `--aws-secretsmanager-pipeline-secret-template`
166+
or `--aws-secretsmanager-team-secret-template` variables.
167+
168+
!!! note
169+
170+
If Concourse does not have [permission](#iam-permissions) to access the pipeline-scoped paths, then credential
171+
lookups will fail even for credentials which are stored at the team level.
172+
173+
## Scaling
174+
175+
If your cluster has a large workload, in particular if there are many resources, Concourse can generate a lot of traffic
176+
to AWS and subsequently get rate-limited.
177+
178+
As long as Concourse has permission to get the value of the `__concourse-health-check` secret, you should be able to
179+
measure an error rate by polling the `/api/v1/info/creds` endpoint when authenticated as
180+
a [Concourse Admin](../../auth-and-teams/user-roles.md#concourse-admin).
181+
182+
Depending on your workflow for updating secrets and your reliability requirements it may be
183+
worth [Caching credentials](caching.md) and/or [Retrying failed fetches](retrying-failed.md) to mitigate
184+
rate-limit-related errors.

‎docs/docs/operation/creds/aws-ssm.md‎

Lines changed: 125 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,130 @@ title: The AWS SSM credential manager
44

55
## Configuration
66

7+
The ATC is configured with an access key and secret key or session token and the AWS region that your parameters are
8+
stored within. If no access key, secret key, or session token is provided, Concourse will attempt to use environment
9+
variables or the instance credentials assigned to the instance.
10+
11+
The ATC's configuration specifies the following:
12+
13+
**`aws-ssm-access-key`**: string
14+
15+
: A valid AWS access key.
16+
17+
: Environment variable `CONCOURSE_AWS_SSM_ACCESS_KEY`.
18+
19+
**`aws-ssm-secret-key`**: string
20+
21+
: The secret key that corresponds to the access key defined above.
22+
23+
: Environment variable `CONCOURSE_AWS_SSM_SECRET_KEY`.
24+
25+
**`aws-ssm-session-token`**: string
26+
27+
: A valid AWS session token.
28+
29+
: Environment variable `CONCOURSE_AWS_SSM_SESSION_TOKEN`.
30+
31+
**`aws-ssm-region`**: string
32+
33+
: The AWS region that requests to parameter store will be sent to.
34+
35+
: Environment variable `CONCOURSE_AWS_SSM_REGION`.
36+
37+
**`aws-ssm-pipeline-secret-template`**: string
38+
39+
: The base path used when attempting to locate a pipeline-level secret.
40+
41+
: Environment variable `CONCOURSE_AWS_SSM_PIPELINE_SECRET_TEMPLATE`.
42+
43+
: !!! example
44+
45+
Default: `/concourse/{{.Team}}/{{.Pipeline}}/{{.Secret}}`
46+
47+
**`aws-ssm-team-secret-template`**: string
48+
49+
: The base path used when attempting to locate a team-level secret.
50+
51+
: Environment variable `CONCOURSE_AWS_SSM_TEAM_SECRET_TEMPLATE`.
52+
53+
: !!! example
54+
55+
Default: `/concourse/{{.Team}}/{{.Secret}}`
56+
57+
For example, to launch the ATC and enable the parameter store, you may configure:
58+
59+
```shell
60+
concourse web ... \
61+
--aws-ssm-region us-east-1 \
62+
--aws-ssm-access-key AKIAIOSFODNN7EXAMPLE \
63+
--aws-ssm-secret-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
64+
65+
# or use env variables
66+
CONCOURSE_AWS_SSM_REGION="us-east-1" \
67+
CONCOURSE_AWS_SSM_ACCESS_KEY="AKIAIOSFODNN7EXAMPLE" \
68+
CONCOURSE_AWS_SSM_SECRET_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
69+
concourse web ...
70+
```
71+
72+
A more secure method is to configure
73+
an [IAM role](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) for your EC2 ATC
74+
instance so that credentials are fetched automatically from the EC2 metadata service.
75+
776
## IAM Permissions
877

9-
## Credential Lookup Rules
78+
The following is an example of an IAM policy that can be used to grant permissions to an IAM user or instance role. Note
79+
that the `Resource` section can contain a wildcard to a parameter or be restricted to an individual parameter.
80+
81+
```json
82+
{
83+
"Version": "2012-10-17",
84+
"Statement": [
85+
{
86+
"Sid": "AllowAccessToSsmParameters",
87+
"Effect": "Allow",
88+
"Action": [
89+
"ssm:GetParameter",
90+
"ssm:GetParametersByPath"
91+
],
92+
"Resource": [
93+
"arn:aws:ssm:::parameter/concourse/*",
94+
"arn:aws:ssm:::parameter/concourse/TEAM_NAME/*",
95+
"arn:aws:ssm:::parameter/concourse/TEAM_NAME/PIPELINE_NAME/*"
96+
]
97+
},
98+
{
99+
"Sid": "AllowAccessToDecryptSsmParameters",
100+
"Effect": "Allow",
101+
"Action": [
102+
"kms:Decrypt",
103+
"kms:DescribeKey"
104+
],
105+
"Resource": "arn:aws:kms:::key/KMS_KEY_ID"
106+
},
107+
{
108+
"Sid": "AllowListKeys",
109+
"Effect": "Allow",
110+
"Action": [
111+
"kms:ListAliases",
112+
"kms:ListKeys"
113+
],
114+
"Resource": "*"
115+
}
116+
]
117+
}
118+
```
119+
120+
Note that the `TEAM_NAME`, `PIPELINE_NAME`, and `KMS_KEY_ID` text above should be replaced to fit your Concourse setup.
121+
122+
For more information on how to use IAM roles to restrict access to SSM parameters, review
123+
the [official documentation](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-access.html).
124+
125+
## Credential Lookup Rules
126+
127+
When resolving a parameter such as `((foo_param))`, Concourse will look in the following paths, in order:
128+
129+
* `/concourse/TEAM_NAME/PIPELINE_NAME/foo_param`
130+
* `/concourse/TEAM_NAME/foo_param`
131+
132+
The leading `/concourse` can be changed by specifying `--aws-ssm-pipeline-secret-template`
133+
or `--aws-ssm-team-secret-template` variables.

‎docs/docs/operation/creds/caching.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,34 @@
11
---
22
title: Caching credentials
33
---
4+
5+
By default, credentials are fetched each time they're used. When many pipelines are configured this can result in a ton
6+
of requests to the credential server.
7+
8+
To reduce load on your credential server you may want to enable caching by setting the following env on
9+
the [`web` node](../../install/running-web.md):
10+
11+
```properties
12+
CONCOURSE_SECRET_CACHE_ENABLED=true
13+
```
14+
15+
Enabling secret caching will cache secrets from both [credential managers](index.md) and
16+
from [var sources](../../vars.md#var-sources-experimental).
17+
18+
By default, credentials will be cached for one minute at a time. This value can be increased to further reduce load on
19+
the server like so:
20+
21+
```properties
22+
CONCOURSE_SECRET_CACHE_DURATION=5m # increase from 1m default
23+
```
24+
25+
Credential cache duration can also be determined by the credential manager itself - for example, if Vault returns a
26+
lease duration for a credential, the shorter value between the configured cache duration and the credential's lease
27+
duration will be used.
28+
29+
By default, the _absence_ of a credential is also cached for 10 seconds so that Concourse doesn't keep looking for a
30+
misconfigured credential. This duration can be configured like so:
31+
32+
```properties
33+
CONCOURSE_SECRET_CACHE_DURATION_NOTFOUND=1s # decrease from 10s default
34+
```

0 commit comments

Comments
 (0)