OSDOCS-12691 [ROSA] New Feature: Log Forwarder

_topic_maps/_topic_map_rosa_hcp.yml

@@ -481,6 +481,8 @@ Distros: openshift-rosa-hcp
 Topics:
 - Name: Adding additional constraints for IP-based AWS role assumption
   File: rosa-adding-additional-constraints-for-ip-based-aws-role-assumption
+- Name: Forwarding control plane logs 
+  File: rosa-forwarding-control-plane-logs
 ---
 Name: Authentication and authorization
 Dir: authentication

modules/rosa-create-an-iam-role-policy.adoc

@@ -0,0 +1,44 @@
+// Module included in the following assemblies:
+//
+// * security/rosa-forwarding-control-plane-logs.adoc
+:_mod-docs-content-type: PROCEDURE
+[id="rosa-create-an-iam-role-policy_{context}"]
+= Creating an IAM role and policy
+
+When you send your logs to a CloudWatch group or S3 bucket, those locations exist outside your control plane. You must create an IAM role and policy so that your log forwarder has the right permissions and capabilities to send these logs to your chosen destination, CloudWatch or S3. 
+
+.Procedure
+
+. To enable the log forwarder delivery capability, prepare the IAM policy by creating an `assume-role-policy.json` file. Apply the following JSON sample: 
++
+[source,json]
+----
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Principal": {
+                "AWS": "arn:aws:iam::859037107838:role/ROSA-CentralLogDistributionRole-241c1a86"
+            },
+            "Action": "sts:AssumeRole"
+        }
+    ]
+}
+----
++
+. To enable the log forwarder distribution capability, create an IAM role that must include the `CustomerLogDistribution` name by running the following command: 
++
+[source,terminal] 
+----
+$ aws iam create-role \
+    --role-name CustomerLogDistribution-RH \
+    --assume-role-policy-document file://assume-role-policy.json
+----
+
+.Next steps
+
+After you create an IAM role and policy, you must decide to send your control plane logs to either a CloudWatch log group, a S3 bucket, or both:
+
+* CloudWatch is typically more expensive than S3. CloudWatch is recommended when you have logs requiring immediate action or organization. To set up CloudWatch, complete the following documentation: xref:../modules/rosa-set-up-cloudwatch-log-group.adoc#rosa-set-up-cloudwatch-log-group[Setting up the CloudWatch log group]. 
+* S3 is typically less expensive than CloudWatch. S3 is recommended when you have logs needing long-term storage or large-scale data analysis. To set up CloudWatch, complete the following documentation: xref:../modules/rosa-set-up-s3-bucket.adoc#rosa-set-up-s3-bucket[Setting up the S3 bucket]. 

modules/rosa-manage-control-plane-log-forwarding.adoc

@@ -0,0 +1,14 @@
+// Module included in the following assemblies:
+//
+// * security/rosa-configuring-the-log-forwarder.adoc
+:_mod-docs-content-type: REFERENCE
+[id="rosa-manage-control-plane-log-forwarding.adoc_{context}"]
+= Managing control plane log forwarding 
+
+After you configure the {product-title} clusters to use your selected log forwarder for managing control plane logs, see the following commands to run based on your specific needs. For all of these commands, you must provide the `clusterid` in the `--cluster` flag: 
+
+* `rosa create log-forwarder -c <cluster_name|cluster_id>` Configures your ROSA cluster to use the log forwarder. 
+* `rosa list log-forwarder -c <cluster_name|cluster_id>`: Displays all the log forwarder configurations attributed to that ROSA cluster. 
+* `rosa describe log-forwarder -c <cluster_name|cluster_id> <log-fwd-id>`:  Provides more than the basic details for that specific log forwarder. 
+* `rosa edit log-forwarder -c <cluster_name|cluster_id> <log-fwd-id>`: Enables you to make changes to the log forwarder. 
+* `rosa delete log-forwarder -c <cluster_name|cluster_id> <log-fwd-id>`: Deletes the log forwarder for all specified ROSA clusters. 

modules/rosa-set-up-cloudwatch-log-group.adoc

@@ -0,0 +1,84 @@
+// Module included in the following assemblies:
+//
+// * security/rosa-forwarding-control-plane-logs.adoc
+:_mod-docs-content-type: PROCEDURE
+[id="rosa-set-up-cloudwatch-log-group.adoc_{context}"]
+= Setting up the CloudWatch log group
+
+Set up the CloudWatch log group for the log forwarder to send logs to by completing the following steps: 
+
+.Procedure
+
+. Create the CloudWatch log group by running the following command: 
++
+[source,terminal]
+----
+$ aws logs create-log-group –log-group-name <your_log_group_name>
+----
++
+. Go to your chosen ROSA cluster and configure the log forwarder to use the CloudWatch log group by applying the following JSON sample:  
++
+[source,json]
+----
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "CreatePutLogs",
+            "Effect": "Allow",
+            "Action": [
+                "logs:CreateLogStream",
+                "logs:PutLogEvents"
+            ],
+            "Resource": "<your_log_group_arn>:*"
+        },
+        {
+            "Sid": "DescribeLogs",
+            "Effect": "Allow",
+            "Action": [
+                "logs:DescribeLogGroups",
+                "logs:DescribeLogStreams"
+            ],
+            "Resource": "*"
+        }
+    ]
+}
+----
++
+. Attached the policy to the CloudWatch role by running the following command: 
++
+[source,terminal]
+----
+$ 	aws iam put-role-policy \
+    --role-name CustomerLogDistribution-RH \
+    --policy-name Allow-CloudWatch-Writes \
+    --policy-document file://cloudwatch-policy.json
+----
++
+. Enable the log forwarder to send logs to your ROSA cluster. 
+.. To create a new cluster for the log forwarder, run the following command:   
++
+[source,terminal]
+----
+$ rosa create cluster --log-fwd-config="<path_to_file>.yaml"
+----
++
+.. To use an existing cluster, run the following command:    
++
+[source,terminal]
+----
+$ rosa create log-forwarder -c <cluster> --log-fwd-config="<path_to_file>.yaml"
+----
++
+. Configure your ROSA cluster to access logs from the CloudWatch log group by applying the following YAML sample:  
++
+[source,yaml]
+----
+cloudwatch:
+  cloudwatch_log_role_arn: "arn:aws:iam::123456789012:role/RosaCloudWatch"
+  cloudwatch_log_group_name: "rosa-logs"
+  applications: "<your chosen application>" 
+  groups: "<your chosen log group>"
+----
+.. For the `applications` property, you can choose any application, for example, `cluster-api`. 
+.. For the `groups` property, you can choose any of the following: `API`, `Authentication`, `Controller Manager`, `Scheduler`, and `Other`.

modules/rosa-set-up-s3-bucket.adoc

@@ -0,0 +1,81 @@
+// Module included in the following assemblies:
+//
+// * security/rosa-forwarding-control-plane-logs.adoc
+:_mod-docs-content-type: PROCEDURE
+[id="rosa-set-up-s3-bucket.adoc_{context}"]
+= Setting up the S3 bucket
+
+Set up the S3 bucket for the log forwarder to send logs to by completing the following steps: 
+
+.Procedure
+
+. Create the S3 bucket by running the following command: 
++
+[source,terminal]
+----
+$ aws s3api create-bucket \
+    --bucket <your_s3_bucket_name> \
+    --region <your_aws_region> \
+    --create-bucket-configuration LocationConstraint=<cluster_aws_region>
+----
++
+. Configure the policy for the S3 bucket by applying the following JSON sample:  
++
+[source,json]
+----
+ "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "AllowCentralLogDistributionWrite",
+            "Effect": "Allow",
+            "Principal": {
+                "AWS": "arn:aws:iam::859037107838:role/ROSA-CentralLogDistributionRole-241c1a86"
+            },
+            "Action": "s3:PutObject",
+            "Resource": "arn:aws:s3:::<your_s3_bucket_name>/*",
+            "Condition": {
+                "StringEquals": {
+                    "s3:x-amz-acl": "bucket-owner-full-control"
+                }
+            }
+        }
+    ]
+}
+----
++
+. Attached the policy to the S3 role by running the following command: 
++
+[source,terminal]
+----
+$ 	aws s3api put-bucket-policy \
+    --bucket <your_s3_bucket_name> \
+    --policy file://s3-bucket-policy.json
+----
++
+. Enable the log forwarder to send logs to your ROSA cluster. 
+.. To create a new cluster for the log forwarder, run the following command:   
++
+[source,terminal]
+----
+$ rosa create cluster --log-fwd-config="<path_to_file>.yaml"
+----
++
+.. To use an existing cluster, run the following command:    
++
+[source,terminal]
+----
+$ rosa create log-forwarder -c <cluster> --log-fwd-config="<path_to_file>.yaml"
+----
++
+. Configure your ROSA cluster to access logs from the S3 bucket by applying the following YAML sample:  
++
+[source,yaml]
+----
+s3:
+  s3_config_bucket_name: "my-log-bucket"
+  s3_config_bucket_prefix: "my-bucket-prefix"
+  applications: "<your chosen application>" 
+  groups: "<your chosen log group>"
+----
+.. For the `applications` property, you can choose any application, for example, `cluster-api`. 
+.. For the `groups` property, you can choose any of the following: `API`, `Authentication`, `Controller Manager`, `Scheduler`, and `Other`.  

security/rosa-forwarding-control-plane-logs.adoc

@@ -0,0 +1,96 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="rosa-forwarding-control-plane-logs_{context}"]
+= Forwarding control plane logs
+
+include::_attributes/attributes-openshift-dedicated.adoc[]
+include::_attributes/common-attributes.adoc[]
+:context: rosa-configuring-the-log-forwarder
+
+toc::[]
+
+[role="_abstract"]
+With {product-title} you have a control plane log forwarder that is a separate system outside your cluster. You can use the control plane log forwarder to send your logs to either a CloudWatch group or S3 bucket, depending on your preference. 
+
+If you build the control plane logs yourself, you must make log forwarding part of the workloads in your cluster. Since the {product-title} log forwarder is in a control plane outside your cluster, it does not take up space or consume resources in your cluster. The {product-title} log forwarder gives your workloads and cluster more bandwidth, making your development processes simpler.
+
+*IMPORTANT:* When you forward control plane logs, you must decide on what log groups you want to use. Log groups cost money, so the more log groups you have, the more money you spend. See the following table to help you decide what log groups you need before you begin to forward your control plane logs: 
+
+|====
+| Log group name| Benefit of that log group| Applications available for that log group  
+
+| API  
+| Records every request made to the cluster. Helps security by detecting unauthorized access attempts.
+a| 
+* `audit-webhook`
+* `kube-apiserver`
+* `oauth-openshift`
+* `openshift-apiserver`
+* `openshift-oauth-apiserver`
+* `packageserver`
+* `validation-webhook`  
+
+| Authentication  
+| Tracks login attempts and requests for tokens. Helps you access the cluster even if your `oc login` does not work. 
+a| 
+* `ignition-server`
+* `konnectivity-agent`
+
+| Controller manager  
+| Monitors the controllers that watch the state of your clusters. Helps explain the difference between the actual state of your cluster and your desired state for it.
+a| 
+* `aws-ebs-csi-driver-controller`
+* `capi-provider-controller-manager`
+* `catalog-operator`
+* `cloud-controller-manager`
+* `cloud-credential-operator`
+* `cloud-network-config-controller`
+* `cluster-network-operator`
+* `cluster-node-tuning-operator`
+* `cluster-policy-controller`
+* `cluster-version-operator`
+* `control-plane-operator`
+* `control-plane-pki-operator`
+* `csi-snapshot-controller-operator`
+* `csi-snapshot-controller`
+* `dns-operator`
+* `hosted-cluster-config-operator`
+* `ingress-operator`
+* `kube-controller-manager`
+* `machine-approver`
+* `multus-admission-controller`
+* `network-node-identity`
+* `olm-operator`
+* `openshift-controller-manager`
+* `openshift-route-controller-manager`
+* `ovnkube-control-plane`   
+
+| Scheduler    
+| Records the placement of each pod on every node. Helps you understand why pods are stuck in a `Pending` state.
+a| 
+* `kube-scheduler`
+
+| Other  
+| Any log group different than `API`, `Authentication`, `Controller manager`, or `Scheduler`.
+a| 
+* `certified-operators-catalog`
+* `cluster-api`
+* `community-operators-catalog`
+* `etcd`
+* `private-router`
+* `redhat-marketplace-catalog`
+* `redhat-operators-catalog`    
+|====
+
+[id="prerequisites_{context}"]
+== Prerequisites
+
+* You have installed and configured the latest {rosa-cli} on your installation host. 
+
+include::modules/rosa-create-an-iam-role-policy.adoc[leveloffset=+1]
+
+include::modules/rosa-set-up-cloudwatch-log-group.adoc[leveloffset=+1]
+
+include::modules/rosa-set-up-s3-bucket.adoc[leveloffset=+1]
+
+include::modules/rosa-manage-control-plane-log-forwarding.adoc[leveloffset=+1]
+