Skip to content

Commit 6375322

Browse files
theashiottheashiot
committed
OBSDOCS-1802: Support Multiple CloudWatch Outputs with unique STS
1 parent 8821808 commit 6375322

4 files changed

+203
-91
lines changed

‎configuring/configuring-log-forwarding.adoc

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,41 @@ Administrators can configure the following types of filters:
116116
include::modules/enabling-multi-line-exception-detection.adoc[leveloffset=+2]
117117
include::modules/logging-http-forward.adoc[leveloffset=+2]
118118
include::modules/cluster-logging-collector-log-forward-syslog.adoc[leveloffset=+2]
119+
120+
121+
[id="forwarding-logs-to-amazon-cloudwatch-from-sts-enabled-clusters_{context}"]
122+
== Forwarding logs to Amazon CloudWatch from STS-enabled clusters
123+
124+
Amazon CloudWatch is a service that helps administrators observe and monitor resources and applications on {aws-first}. You can forward logs from {loggingproductname} to CloudWatch securely by leveraging {aws-short}'s Identity and Access Management (IAM) Roles for Service Accounts (IRSA), which uses {aws-short} {sts-first}.
125+
126+
The authentication with CloudWatch works as follows:
127+
128+
. The log collector requests temporary {aws-short} credentials from {sts-first} by presenting its service account token to the OpenID Connect (OIDC) provider in {aws-short}.
129+
. {aws-short} validates the token. Afterward, depending on the trust policy, {aws-short} issues short-lived, temporary credentials, including an access key ID, secret access key, and session token, for the log collector to use.
130+
131+
On {sts-short}-enabled clusters such as {product-rosa}, {aws-short} roles are pre-configured with the required trust policies. This allows service accounts to assume the roles. Therefore, you can create a secret for {aws-short} with {sts-short} that uses the IAM role. You can then create or update a `ClusterLogForwarder` custom resource (CR) that uses the secret to forward logs to CloudWatch output. Follow these procedures to create a secret and a `ClusterLogForwarder` CR if roles have been pre-configured:
132+
133+
////
134+
* xref:../modules/cluster-logging-collector-log-forward-secret-cloudwatch.adoc#cluster-logging-collector-log-forward-secret-cloudwatch_configuring-log-forwarding[Creating a secret for CloudWatch with an existing {aws-short} role]
135+
136+
* xref:../modules/cluster-logging-collector-log-forward-sts-cloudwatch.adoc#cluster-logging-collector-log-forward-sts-cloudwatch_configuring-log-forwarding[Forwarding logs to Amazon CloudWatch from STS enabled clusters]
137+
////
138+
* Creating a secret for CloudWatch with an existing {aws-short} role
139+
140+
* Forwarding logs to Amazon CloudWatch from STS-enabled clusters
141+
142+
If you do not have an {aws-short} IAM role pre-configured with trust policies, you must first create the role with the required trust policies. Complete the following procedures to create a secret, `ClusterLogForwarder` CR, and role.
143+
144+
////
145+
* xref:../modules/creating-an-aws-role.adoc#creating-an-aws-role_configuring-log-forwarding[Creating an AWS IAM role]
146+
* xref:../modules/cluster-logging-collector-log-forward-secret-cloudwatch.adoc#cluster-logging-collector-log-forward-secret-cloudwatch_configuring-log-forwarding[Creating a secret for AWS CloudWatch with an existing AWS role]
147+
* xref:../modules/cluster-logging-collector-log-forward-sts-cloudwatch.adoc#cluster-logging-collector-log-forward-sts-cloudwatch[Forwarding logs to Amazon CloudWatch from STS enabled clusters]
148+
////
149+
150+
include::modules/creating-an-aws-role.adoc[leveloffset=+2]
151+
include::modules/cluster-logging-collector-log-forward-secret-cloudwatch.adoc[leveloffset=+2]
152+
include::modules/cluster-logging-collector-log-forward-sts-cloudwatch.adoc[leveloffset=+2]
153+
119154
include::modules/logging-content-filter-drop-records.adoc[leveloffset=+2]
120155
include::modules/logging-audit-log-filtering.adoc[leveloffset=+2]
121156
include::modules/input-spec-filter-labels-expressions.adoc[leveloffset=+2]

‎modules/cluster-logging-collector-log-forward-secret-cloudwatch.adoc

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,25 @@
11
// Module included in the following assemblies:
22
//
3-
// * observability/logging/cluster-logging-external.adoc
3+
// * configuring/configuring-log-forwarding.adoc
44

55
:_mod-docs-content-type: PROCEDURE
66
[id="cluster-logging-collector-log-forward-secret-cloudwatch_{context}"]
77
= Creating a secret for AWS CloudWatch with an existing AWS role
8-
If you have an existing role for AWS, you can create a secret for AWS with STS using the `oc create secret --from-literal` command.
8+
9+
Create a secret for {aws-first} {sts-first} from the configured {aws-short} IAM role by using the `oc create secret --from-literal` command.
10+
11+
.Prerequisites
12+
13+
* You have created an {aws-short} IAM role.
14+
* You have administrator access to {product-title}.
915
1016
.Procedure
1117

1218
* In the CLI, enter the following to generate a secret for AWS:
1319
+
1420
[source,terminal]
1521
----
16-
$ oc create secret generic cw-sts-secret -n openshift-logging --from-literal=role_arn=arn:aws:iam::123456789012:role/my-role_with-permissions
22+
$ oc create secret generic sts-secret -n openshift-logging --from-literal=role_arn=arn:aws:iam::123456789012:role/openshift-logger
1723
----
1824
+
1925
.Example Secret
@@ -23,7 +29,7 @@ apiVersion: v1
2329
kind: Secret
2430
metadata:
2531
namespace: openshift-logging
26-
name: my-secret-name
32+
name: sts-secret
2733
stringData:
28-
role_arn: arn:aws:iam::123456789012:role/my-role_with-permissions
34+
role_arn: arn:aws:iam::123456789012:role/openshift-logger
2935
----

‎modules/cluster-logging-collector-log-forward-sts-cloudwatch.adoc

Lines changed: 40 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,111 +1,65 @@
11
// Module included in the following assemblies:
22
//
3-
// * observability/logging/log_collection_forwarding/configuring-log-forwarding.adoc
3+
// * configuring/configuring-log-forwarding.adoc
4+
5+
//https://github.com/openshift/cluster-logging-operator/blob/master/docs/features/logforwarding/outputs/cloudwatch-sts-forwarding.adoc
46

57
:_mod-docs-content-type: PROCEDURE
68
[id="cluster-logging-collector-log-forward-sts-cloudwatch_{context}"]
7-
= Forwarding logs to Amazon CloudWatch from STS enabled clusters
9+
= Forwarding logs to Amazon CloudWatch from STS-enabled clusters
810

9-
For clusters with AWS Security Token Service (STS) enabled, you can create an AWS service account manually or create a credentials request by using the Cloud Credential Operator (CCO) utility `ccoctl`.
11+
You can forward logs from {logging-title} deployed on clusters with {aws-first} {sts-first}-enabled to Amazon CloudWatch. Amazon CloudWatch is a service that helps administrators observe and monitor resources and applications on {aws-short}.
1012

1113
.Prerequisites
1214

13-
* {logging-title-uc}: 5.5 and later
15+
* {clo} has been installed.
16+
* You have configured a credential secret.
17+
* You have administrator access to {product-title}.
1418
1519
.Procedure
1620

17-
. Create a `CredentialsRequest` custom resource YAML by using the template below:
21+
* Create or update a `ClusterLogForwarder` custom resource (CR):
1822
+
19-
.CloudWatch credentials request template
2023
[source,yaml]
2124
----
22-
apiVersion: cloudcredential.openshift.io/v1
23-
kind: CredentialsRequest
24-
metadata:
25-
name: <your_role_name>-credrequest
26-
namespace: openshift-cloud-credential-operator
27-
spec:
28-
providerSpec:
29-
apiVersion: cloudcredential.openshift.io/v1
30-
kind: AWSProviderSpec
31-
statementEntries:
32-
- action:
33-
- logs:PutLogEvents
34-
- logs:CreateLogGroup
35-
- logs:PutRetentionPolicy
36-
- logs:CreateLogStream
37-
- logs:DescribeLogGroups
38-
- logs:DescribeLogStreams
39-
effect: Allow
40-
resource: arn:aws:logs:*:*:*
41-
secretRef:
42-
name: <your_role_name>
43-
namespace: openshift-logging
44-
serviceAccountNames:
45-
- logcollector
46-
----
47-
+
48-
. Use the `ccoctl` command to create a role for AWS using your `CredentialsRequest` CR. With the `CredentialsRequest` object, this `ccoctl` command creates an IAM role with a trust policy that is tied to the specified OIDC identity provider, and a permissions policy that grants permissions to perform operations on CloudWatch resources. This command also creates a YAML configuration file in `/<path_to_ccoctl_output_dir>/manifests/openshift-logging-<your_role_name>-credentials.yaml`. This secret file contains the `role_arn` key/value used during authentication with the AWS IAM identity provider.
49-
+
50-
[source,terminal]
51-
----
52-
$ ccoctl aws create-iam-roles \
53-
--name=<name> \
54-
--region=<aws_region> \
55-
--credentials-requests-dir=<path_to_directory_with_list_of_credentials_requests>/credrequests \
56-
--identity-provider-arn=arn:aws:iam::<aws_account_id>:oidc-provider/<name>-oidc.s3.<aws_region>.amazonaws.com <1>
57-
----
58-
<1> <name> is the name used to tag your cloud resources and should match the name used during your STS cluster install
59-
+
60-
. Apply the secret created:
61-
[source,terminal]
62-
+
63-
----
64-
$ oc apply -f output/manifests/openshift-logging-<your_role_name>-credentials.yaml
65-
----
66-
+
67-
. Create or edit a `ClusterLogForwarder` custom resource:
68-
+
69-
[source,yaml]
70-
----
71-
apiVersion: logging.openshift.io/v1
25+
apiVersion: observability.openshift.io/v1
7226
kind: ClusterLogForwarder
7327
metadata:
74-
name: <log_forwarder_name> <1>
75-
namespace: <log_forwarder_namespace> <2>
28+
name: <log_forwarder_name>
29+
namespace: openshift-logging
7630
spec:
77-
serviceAccountName: clf-collector <3>
31+
serviceAccount:
32+
name: <service_account_name> #<1>
7833
outputs:
79-
- name: cw <4>
80-
type: cloudwatch <5>
34+
- name: cw-output #<2>
35+
type: cloudwatch #<3>
8136
cloudwatch:
82-
groupBy: logType <6>
83-
groupPrefix: <group prefix> <7>
84-
region: us-east-2 <8>
85-
secret:
86-
name: <your_secret_name> <9>
37+
groupName: 'cw-projected{.log_type||"missing"}' #<4>
38+
region: us-east-2 #<5>
39+
authentication:
40+
type: iamRole #<6>
41+
iamRole:
42+
roleARN: #<7>
43+
key: role_arn
44+
secretName: sts-secret
45+
token: #<8>
46+
from: serviceAccount
8747
pipelines:
88-
- name: to-cloudwatch <10>
89-
inputRefs: <11>
48+
- name: to-cloudwatch
49+
inputRefs: #<9>
9050
- infrastructure
9151
- audit
9252
- application
93-
outputRefs:
94-
- cw <12>
53+
outputRefs: #<10>
54+
- cw-output
9555
----
96-
<1> In legacy implementations, the CR name must be `instance`. In multi log forwarder implementations, you can use any name.
97-
<2> In legacy implementations, the CR namespace must be `openshift-logging`. In multi log forwarder implementations, you can use any namespace.
98-
<3> Specify the `clf-collector` service account. The service account is only required in multi log forwarder implementations if the log forwarder is not deployed in the `openshift-logging` namespace.
99-
<4> Specify a name for the output.
100-
<5> Specify the `cloudwatch` type.
101-
<6> Optional: Specify how to group the logs:
102-
+
103-
* `logType` creates log groups for each log type.
104-
* `namespaceName` creates a log group for each application name space. Infrastructure and audit logs are unaffected, remaining grouped by `logType`.
105-
* `namespaceUUID` creates a new log groups for each application namespace UUID. It also creates separate log groups for infrastructure and audit logs.
106-
<7> Optional: Specify a string to replace the default `infrastructureName` prefix in the names of the log groups.
107-
<8> Specify the AWS region.
108-
<9> Specify the name of the secret that contains your AWS credentials.
109-
<10> Optional: Specify a name for the pipeline.
110-
<11> Specify which log types to forward by using the pipeline: `application,` `infrastructure`, or `audit`.
111-
<12> Specify the name of the output to use when forwarding logs with this pipeline.
56+
<1> Specify the service account.
57+
<2> Specify a name for the output.
58+
<3> Specify the `cloudwatch` type.
59+
<4> Specify the group name for the log stream.
60+
<5> Specify the AWS region.
61+
<6> Specify `iamRole` as the authentication type for STS.
62+
<7> Specify the name of the secret and the key where the `role_arn` resource is stored.
63+
<8> Specify the service account token to use for authentication. To use the projected service account token, use `from: serviceAccount`.
64+
<9> Specify which log types to forward by using the pipeline: `application,` `infrastructure`, or `audit`.
65+
<10> Specify the names of the output to use when forwarding logs with this pipeline.

‎modules/creating-an-aws-role.adoc

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
:_newdoc-version: 2.18.4
2+
:_template-generated: 2025-06-24
3+
:_mod-docs-content-type: PROCEDURE
4+
5+
[id="creating-an-aws-role_{context}"]
6+
= Creating an {aws-short} IAM role
7+
8+
Create an {aws-first} IAM role that your service account can assume to securely access AWS resources.
9+
10+
The following procedure demonstrates creating an {aws-short} IAM role by using the {aws-short} CLI. You can alternatively use the Cloud Credential Operator (CCO) utility `ccoctl`. Using the `ccoctl` utility creates many fields in the IAM role policy that are not required by the `ClusterLogForwarder` custom resource (CR). These extra fields are ignored by the CR. However, the `ccoctl` utility provides a convenient way for configuring IAM roles. For more information see link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/authentication_and_authorization/managing-cloud-provider-credentials#cco-short-term-creds[Manual mode with short-term credentials for components].
11+
12+
.Prerequisites
13+
14+
* You have access to an {product-title} cluster with {sts-first} enabled and configured for {aws-short}.
15+
* You have administrator access to the {aws-short} account.
16+
* {aws-short} CLI installed.
17+
18+
.Procedure
19+
20+
. Create an IAM policy that grants permissions to write logs to CloudWatch.
21+
22+
.. Create a file, for example `cw-iam-role-policy.json`, with the following content:
23+
+
24+
[source,json]
25+
----
26+
{
27+
"Version": "2012-10-17",
28+
"Statement": [
29+
{
30+
"Effect": "Allow",
31+
"Action": [
32+
"logs:PutLogEvents",
33+
"logs:CreateLogGroup",
34+
"logs:PutRetentionPolicy",
35+
"logs:CreateLogStream",
36+
"logs:DescribeLogGroups",
37+
"logs:DescribeLogStreams"
38+
],
39+
"Resource": "arn:aws:logs:*:*:*"
40+
}
41+
]
42+
}
43+
----
44+
45+
.. Create the IAM policy based on the previous policy definition by running the following command:
46+
+
47+
[source,terminal]
48+
----
49+
aws iam create-policy \
50+
--policy-name cluster-logging-allow \
51+
--policy-document file://cw-iam-role-policy.json
52+
----
53+
+
54+
Note the `Arn` value of the created policy.
55+
56+
. Create a trust policy to allow the logging service account to assume an IAM role:
57+
58+
.. Create a file, for example `cw-trust-policy.json`, with the following content:
59+
+
60+
[source,json]
61+
----
62+
{
63+
"Version": "2012-10-17",
64+
"Statement": [
65+
{
66+
"Effect": "Allow",
67+
"Principal": {
68+
"Federated": "arn:aws:iam::123456789012:oidc-provider/<OPENSHIFT_OIDC_PROVIDER_URL>" //<1>
69+
},
70+
"Action": "sts:AssumeRoleWithWebIdentity",
71+
"Condition": {
72+
"StringEquals": {
73+
"<OPENSHIFT_OIDC_PROVIDER_URL>:sub": "system:serviceaccount:openshift-logging:logcollector" //<2>
74+
}
75+
}
76+
}
77+
]
78+
}
79+
----
80+
<1> Replace `<OPENSHIFT_OIDC_PROVIDER_URL>` with the URL of your {product-title} OIDC URL.
81+
<2> The namespace and service account must match the namespace and service account that the log forwarder uses.
82+
83+
. Create an IAM role based on the previously defined trust policy by running the following command:
84+
+
85+
[source,terminal]
86+
----
87+
$ aws iam create-role --role-name openshift-logger --assume-role-policy-document file://cw-trust-policy.json
88+
----
89+
+
90+
Note the `Arn` value of the created role.
91+
92+
. Attach the policy to the role by running the following command:
93+
+
94+
[source,terminal]
95+
----
96+
$ aws iam put-role-policy \
97+
--role-name openshift-logger --policy-name cluster-logging-allow \
98+
--policy-document file://cw-role-policy.json
99+
----
100+
101+
.Verification
102+
* Verify the role and the permissions policy by running the following command:
103+
+
104+
[source,terminal]
105+
----
106+
$ aws iam get-role --role-name openshift-logger
107+
----
108+
+
109+
.Example output
110+
[source,options="nowrap"]
111+
----
112+
ROLE arn:aws:iam::123456789012:role/openshift-logger
113+
ASSUMEROLEPOLICYDOCUMENT 2012-10-17
114+
STATEMENT sts:AssumeRoleWithWebIdentity Allow
115+
STRINGEQUALS system:serviceaccount:openshift-logging:openshift-logger
116+
PRINCIPAL arn:aws:iam::123456789012:oidc-provider/<OPENSHIFT_OIDC_PROVIDER_URL>
117+
----

0 commit comments

Comments
 (0)