Skip to content

Commit 0ee2df7

Browse files
rafaelpereyrabryan-aguilar
rafaelpereyra
and
bryan-aguilar
authored
Added IAM Roles Anywhere documentation (#446)
* Added IAM Roles Anywhere documentation Fix #429 Added instructions to configure credential process for systemd based Linux Added references to the AWS Documentation * Feedback fixes - Removed blog post reference. - Added detail on how to setup IAM Roles Anywhere (high level) --------- Co-authored-by: bryan-aguilar <[email protected]>
1 parent c69b5e8 commit 0ee2df7

File tree

1 file changed

+114
-0
lines changed

1 file changed

+114
-0
lines changed

‎src/docs/setup/on-premises.mdx

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,3 +45,117 @@ following folder layout.
4545
sudo /opt/aws/aws-otel-collector/bin/aws-otel-collector-ctl -a status
4646
```
4747

48+
49+
<SectionSeparator />
50+
51+
## Configure AWS IAM Roles Anywhere
52+
53+
AWS Introduced [IAM Roles Anywhere](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/introduction.html) to allow
54+
workloads to obtain temporary security credentials in IAM. ADOT can leverage this service to obtain the credentials needed for
55+
the exporters that target AWS (CloudWatch EMF, X-Ray, Amazon Managed Service for Prometheus).
56+
57+
In order to leverage IAM Roles Anywhere on your on-premises environment you'll need to create:
58+
59+
* A [trust anchor](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/introduction.html#first-time-user) that is trusted by both AWS
60+
and your Certificate Authority of choice.
61+
* An IAM Role for ADOT Collector with proper permissions to interact with Amazon Managed Services for Prometheus.
62+
* A [profile](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/introduction.html#first-time-user) to specify what roles can be assumed by your workload through the trust anchor in IAM Roles Anywhere.
63+
* End user certificate used by ADOT Collector to [obtain temporary AWS credentials](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/credential-helper.html).
64+
65+
1. A Trust Anchor is a reference to a Certificate Authority Certificate trusted by you. You have two options:
66+
67+
* Use [AWS Private Certificate Authority (AWS Private CA)](https://docs.aws.amazon.com/privateca/latest/userguide/PcaWelcome.html) that integrates with IAM Roles Anywhere on the same account.
68+
* Use an external Certificate Authority by importing the CA Certificate Body in AWS in Privacy Enhanced Mail (PEM) format.
69+
70+
You can create an IAM Roles Anywhere trust anchor following the [AWS documentation](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/getting-started.html#getting-started-step1):
71+
72+
2. Create an IAM Role with the permissions needed for your workload. An example of the IAM policies can be found in the AWS Documentation for [Amazon Managed Service for Prometheus](https://docs.aws.amazon.com/prometheus/latest/userguide/security_iam_id-based-policy-examples.html#security_iam_amp_policies),
73+
and create a trust policy to allow IAM Roles Anywhere service to assume the role on behalf of your workload as described in the [AWS Documentation](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/getting-started.html#getting-started-step2)
74+
75+
It's [recommended](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/trust-model.html#trust-policy) to include conditions
76+
in the trust policy using attributes from the X.509 certificate. For example the following trust policy restricts the actions by using
77+
the certificate Subject Common Name (CN) attribute.
78+
79+
```json
80+
{
81+
"Version": "2012-10-17",
82+
"Statement": [
83+
{
84+
"Sid": "",
85+
"Effect": "Allow",
86+
"Principal": {
87+
"Service": "rolesanywhere.amazonaws.com"
88+
},
89+
"Action": [
90+
"sts:AssumeRole",
91+
"sts:SetSourceIdentity",
92+
"sts:TagSession"
93+
],
94+
"Condition": {
95+
"StringEquals": {
96+
"aws:PrincipalTag/x509Subject/CN": "VM01"
97+
}
98+
}
99+
}
100+
]
101+
}
102+
```
103+
104+
3. Create a profile on IAM Roles Anywhere to match the IAM Role created in the previous step with the Trust Anchor created on Step 1.
105+
106+
4. Create a private key pair and end user certificate for your workload. Instructions to perform this operation depends on your OS as well as
107+
the Certificate Authority of choice. An example of how to generate and end user certificate for AWS Private CA can be found in the [AWS Documentation](https://docs.aws.amazon.com/privateca/latest/userguide/PcaIssueCert.html).
108+
109+
## Configuring ADOT Collector to use IAM Roles Anywhere
110+
111+
112+
1. Install credential helper tool (`aws_signing_helper`) as instructed in the [AWS documentation](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/credential-helper.html). Ensure the tool is included in the system PATH.
113+
114+
2. Create a home folder for the `aoc` user, copy the X509 certificate and private key.
115+
116+
```
117+
mkdir /home/aoc/.x509
118+
mv <x509_private_key> /home/aoc/.x509/private-key.pem
119+
mv <x509_certificate> /home/aoc/.x509/cert.pem
120+
chown -R aoc:aoc /home/aoc/.x509/
121+
122+
echo "AWS_CONFIG_FILE=/home/aoc/.x509/config" | sudo tee -a /opt/aws/aws-otel-collector/etc/.env
123+
```
124+
125+
3. Create an AWS SDK configuration (`config`) to use credential helper tool to generate temporary credentials using the provided X509 key and certificate.
126+
You'll need to provide the following values from your AWS Environment. You can find more information in the [AWS documentation](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/credential-helper.html#credential-helper-options):
127+
128+
- `TA_ARN`: `--trust-anchor-arn` ARN of Trust anchor to to use for authentication.
129+
- `PROFILE_ID_ARN`: `--profile-arn` ARN of the profile to pull policies from.
130+
- `REMOTE_ROLE`: `--role-arn` Target role to assume.
131+
132+
Note that we stored the certificate and private keys in the `aoc` user home folder inside the `.x509` directory. If you use a different path
133+
you'll need to update the configuration accordingly.
134+
135+
```
136+
export TA_ARN=<Trust Anchor ARN>
137+
export PROFILE_ID_ARN=<Profile ID ARN>
138+
export REMOTE_ROLE=<Role ARN with AWS permission>
139+
140+
cat > config << EOF
141+
[default]
142+
credential_process = aws_signing_helper credential-process --certificate /home/aoc/.x509/cert.pem --private-key /home/aoc/.x509/private-key.pem --trust-anchor-arn $TA_ARN --profile-arn $PROFILE_ID_ARN --role-arn $REMOTE_ROLE
143+
EOF
144+
145+
sudo chown aoc:aoc config
146+
sudo mv config /home/aoc/.x509/
147+
```
148+
149+
4. Add `AWS_CONFIG_FILE` environment variable to the ADOT Collector configuration by adding an entry in the `.env` file used to load
150+
the service. *Note that this file is only loaded for `systemd` enabled Linux distributions. For other systems you might need to make additional modifications to load the environment variable before running the service.*
151+
152+
```
153+
echo "AWS_CONFIG_FILE=/home/aoc/.x509/config" | sudo tee -a /opt/aws/aws-otel-collector/etc/.env
154+
```
155+
156+
5. Restart the ADOT Collector to use the newly configured role.
157+
158+
```
159+
sudo /opt/aws/aws-otel-collector/bin/aws-otel-collector-ctl -a stop
160+
sudo /opt/aws/aws-otel-collector/bin/aws-otel-collector-ctl -a start
161+
```

0 commit comments

Comments
 (0)