align readme

Signed-off-by: desmax74 <[email protected]>
trustification · Oct 11, 2024 · 7edb93d · 7edb93d
1 parent 241e8fb
commit 7edb93d
Show file tree

Hide file tree

Showing 3 changed files with 257 additions and 94 deletions.
diff --git a/README.md b/README.md
@@ -1,28 +1,195 @@
-# trustification-ansible
+# Red Hat Trusted Profile Analyzer Ansible collection
 
-Automation to deploy the Trustification project on RH OS family
+The purpose of this Ansible collection is to automate the deployment of the Red Hat Trusted Profile Analyzer (RHTPA) service on Red Hat Enterprise Linux (RHEL).
 
-:warning: **The contents of this repository are a Work in Progress.**
+> [!IMPORTANT]
+Deploying RHTPA by using Ansible is a Technology Preview feature only.
+Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production.
+These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
+See the support scope for [Red Hat Technology Preview](https://access.redhat.com/support/offerings/techpreview/) features for more details.
 
-## Overview
 
-The automation within this repository establishes the components of Trustification, the downstream redistribution of [Trustification project](https://github.com/trustification/trustification) within a single Red Hat Enterprise Linux (RHEL) or Fedora machine using a standalone containerized deployment. Containers are spawned using Kubernetes based manifests using
-[podman kube play](https://docs.podman.io/en/latest/markdown/podman-kube-play.1.html).
+## Description
+
+The RHTPA service is the downstream redistribution of the [Trustification](https://github.com/trustification/trustification) project.
+The automation contained within this Git repository installs and configures the components of RHTPA to run on a single RHEL server, which uses a standalone containerized deployment.
+A Kubernetes-based manifest creates containers that uses [`podman kube play`](https://docs.podman.io/en/latest/markdown/podman-kube-play.1.html).
 
-The following Trustification components are deployed as part of this architecture:
+The RHTPA Ansible collection deploys the following RHTAS components:
 
 - [Trustification](https://github.com/trustification/trustification)
 - [Guac](https://github.com/trustification/guac)
 
-The following components are used if provided by the customers:
+An [NGINX](https://www.nginx.com) front end places an entrypoint to the RHTPA UI.
+A set of self-signed certificates get generated at runtime to establishing secure communications.
+
+The ingress host name is follow, where `<base_hostname>` is your deployment's base hostname:
+* https://`<base_hostname>`
+
+## Requirements
+
+* Ansible 2.16.0 or greater
+* Python 3.9.0 or greater
+* RHEL x86\_64 9.2 or greater.
+* Installation and configuration of Ansible on a control node to perform the automation.
+* Installation of the Ansible collections on the control node.
+  * If installing from the Ansible Automation Hub, then run `ansible-galaxy install redhat.trusted_profile_analyzer`.
+  * If installing from this Git repository, then clone it locally, and run `ansible-galaxy collection install -r requirements.yml`.
+* An OpenID Connect (OIDC) provider, such as [Keycloak](https://console.redhat.com/ansible/automation-hub/repo/published/redhat/sso/).
+* A PostgreSQL instance
+* SQS like [Kafka](https://console.redhat.com/ansible/automation-hub/repo/published/redhat/amq_streams/)
+* S3 service or S3 compatible service
+* Optional:
+  Installation of the `podman` binaries to verify that the RHTPA service is working as expected.
+
+## Overview
+The following components are provided by the customers:
+
+### RedHat Single Sign On
+  For this, you will need to:
+
+  * Install Keycloak
+  * Create a new realm
+  * Create the following roles for this realm
+   * `chicken-user`
+   * `chicken-manager`
+   * `chicken-admin`
+  * Make the `chicken-user` a default role
+  * Create the following scopes for this realm
+    * `read:document`
+    * `create:document`
+    * `delete:document`
+  * Add the `create:document` and `delete:document` scope to the `chicken-manager` role
+  * Create two clients
+    *  One public client
+        * Set `standardFlowEnabled` to `true`
+        * Set `fullScopedAllowed` to `true`
+        * Set the following `defaultClientScopes`
+          * `read:document`
+          * `create:document`
+          * `delete:document`
+    * One protected client  
+        * Set `publicClient` to `false`
+        * Set `serviecAccountsEnabled` to `true`
+        * Set `fullScopedAllowed` to `true`
+        * Set the following `defaultClientScopes`
+          * `read:document`
+          * `create:document`
+        * Add role `chicken-manager` to the service account of this client
+    * Increase the token timeout for both clients to at least 5 minutes
+    * Create a user, acting as administrator
+    * Add the `chicken-manager` and `chicken-admin` role to this user
+
+
+
+### RedHat Kafka streams  
+  With the following topic names created:
+```
+  bombastic-failed-default
+  bombastic-indexed-default
+  bombastic-stored-default
+  vexination-failed-default
+  vexination-indexed-default
+  vexination-stored-default
+  v11y-failed-default
+  v11y-indexed-default
+  v11y-stored-default
+```
+configured in the main.yml
+
+### Postgresql
+
+### S3 or S3 compatible service like Minio
+  Have the following unversioned S3 bucket names created:
+  ```
+  bombastic-default
+  vexination-default
+  v11y-default 
+  ```
+  configured in the main.yml
+
+
+*  Details about how to configure the services can be found here [RHTPA external services deploy](https://docs.redhat.com/en/documentation/red_hat_trusted_profile_analyzer/1/html-single/deployment_guide/index#installing-trusted-profile-analyzer-by-using-helm-with-other-services_deploy)
+* [Trustification](https://github.com/trustification/trustification/blob/main/docs/modules/admin/pages/cluster-preparing.adoc)
+
+
 
-- RH Single Sign On
-- RH Kafka streams
-- Postgresql
-- S3 or compatible service like Minio
 
 Utilize the steps below to understand how to setup and execute the provisioning.
 
+## Installation
+
+
+Before using this collection, you need to install it with the Ansible Galaxy command-line tool:
+
+```
+ansible-galaxy collection install redhat.trusted_profile_analyzer
+```
+
+You can also include it in a `requirements.yml` file and install it with `ansible-galaxy collection install -r requirements.yml`, using the format:
+
+
+```yaml
+collections:
+  - name: redhat.trusted_profile_analyzer
+```
+
+Note that if you install any collections from Ansible Galaxy, they will not be upgraded automatically when you upgrade the Ansible package.
+To upgrade the collection to the latest available version, run the following command:
+
+```
+ansible-galaxy collection install redhat.trusted_profile_analyzer --upgrade
+```
+
+You can also install a specific version of the collection, for example, if you need to downgrade when something is broken in the latest version (please report an issue in this repository). Use the following syntax to install version 1.2.0:
+
+```
+ansible-galaxy collection install redhat.trusted_profile_analyzer:==1.2.0
+```
+
+## Verifying the deployment
+
+1. Export the following environment variables, replacing `TODO` with your relevant information:
+
+   ```shell
+      export TPA_SINGLE_NODE_REGISTRATION_USERNAME=<Your Red Hat subscription username>
+      export TPA_SINGLE_NODE_REGISTRATION_PASSWORD=<Your Red Hat subscription password>
+      export TPA_SINGLE_NODE_REGISTRY_USERNAME=<Your Red Hat image registry username>
+      export TPA_SINGLE_NODE_REGISTRY_PASSWORD=<Your Red Hat image registry password>
+      export TPA_PG_HOST=<POSTGRES_HOST_IP>
+      export TPA_PG_USER=<DB_USER>
+      export TPA_PG_PASSWORD==<DB_PASSWORD>
+      export TPA_STORAGE_ACCESS_KEY=<Storage Access Key>
+      export TPA_STORAGE_SECRET_KEY=<Storage Secret Key>
+      export TPA_OIDC_ISSUER_URL=<AWS Cognito or Keycloak Issuer URL. Incase of Keycloak endpoint auth/realms/chicken is needed>
+      export TPA_OIDC_FRONTEND_ID=<OIDC Frontend Id>
+      export TPA_OIDC_PROVIDER_CLIENT_ID=<OIDC Walker Id>
+      export TPA_OIDC_PROVIDER_CLIENT_SECRET=<OIDC Walker Secret>
+      export TPA_EVENT_ACCESS_KEY_ID=<Kafka Username or AWS SQS Access Key>
+      export TPA_EVENT_SECRET_ACCESS_KEY=<Kafka User Password or AWS SQS Secret Key>
+   ```
+2. In case of Kafka Events, create environmental variable for bootstrap server
+```shell
+export TPA_EVENT_BOOTSTRAP_SERVER=<Kafka Bootstrap Server>
+```
+
+3. In case of AWS Cognito as OIDC, create environmental variable for Cognito Domain
+```shell
+export TPA_OIDC_COGNITO_DOMAIN=<AWS Cognito Domain>
+```
+
+4. Open the browser to call the UI
+   https://`<base_hostname>`
+
+
+
+
+
+
+
+
+
+
 ## Prerequisites
 
 A RHEL 9.3+ server should be used to run the Trustification components.
@@ -41,7 +208,7 @@ ansible-galaxy collection install -r requirements.yml
 
 ### OIDC provider
 
-An installation of RH SSO/Keycloak/AWS Cognito must be provided to allow for integration with containerized Trustification.
+An installation of Red Hat SSO/Keycloak/AWS Cognito must be provided to allow for integration with containerized Trustification.
 
 ## Provision