Moving docs to Antora docs folder

keycloak · May 23, 2023 · 93aef8d · 93aef8d
1 parent 7361929
commit 93aef8d
Show file tree

Hide file tree

Showing 15 changed files with 142 additions and 82 deletions.
diff --git a/doc/kubernetes/modules/ROOT/nav.adoc b/doc/kubernetes/modules/ROOT/nav.adoc
@@ -3,12 +3,15 @@
 * xref:present-and-future.adoc[]
 * xref:limitations.adoc[]
 * xref:architecture.adoc[]
-* xref:installation.adoc[]
+* xref:installation-minikube.adoc[]
 ** xref:prerequisite/prerequisite-minikube.adoc[]
 ** xref:prerequisite/prerequisite-helm.adoc[]
 ** xref:prerequisite/prerequisite-kubectl.adoc[]
 ** xref:prerequisite/prerequisite-task.adoc[]
 ** xref:prerequisite/prerequisite-yq.adoc[]
+* xref:openshift.adoc[]
+** xref:prerequisite/prerequisite-rosa.adoc[]
+** xref:prerequisite/prerequisite-openshift.adoc[]
 * xref:customizing-deployment.adoc[]
 * xref:storage-configurations.adoc[]
 ** xref:storage/postgres.adoc[]
@@ -28,6 +31,4 @@
 ** xref:util/custom-image-for-keycloak.adoc[]
 ** xref:util/cryostat.adoc[]
 ** xref:util/task.adoc[]
-* xref:openshift.adoc[]
-** xref:prerequisite/prerequisite-openshift.adoc[]
 * xref:other.adoc[]
diff --git a/doc/kubernetes/modules/ROOT/pages/customizing-deployment.adoc b/doc/kubernetes/modules/ROOT/pages/customizing-deployment.adoc
@@ -230,7 +230,7 @@ NOTE: This option is implemented only for Openshift deployments.
 
 [[KC_PORT_OFFSET,KC_PORT_OFFSET]]
 KC_PORT_OFFSET::
-This parameter allows to change the port by some offset for each service created. This is useful when multiple Keycloak instances are deployed to the same cluster. See section xref:openshift.adoc#sharing-cluster-with-multiple-users[Sharing cluster with multiple users] for more information.
+This parameter allows to change the port by some offset for each service created. This is useful when multiple Keycloak instances are deployed to the same cluster. See section xref:installation-openshift.adoc#sharing-cluster-with-multiple-users[Sharing cluster with multiple users] for more information.
 +
 Default value: 0
 +

diff --git a/...etes/modules/ROOT/pages/installation.adoc → ...les/ROOT/pages/installation-minikube.adoc b/...etes/modules/ROOT/pages/installation.adoc → ...les/ROOT/pages/installation-minikube.adoc
@@ -1,4 +1,5 @@
-= Installing Keycloak on Minikube
+= Installing on Minikube
+:page-aliases: installation.adoc
 
 == Prerequisites to the installation
 

diff --git a/...ernetes/modules/ROOT/pages/openshift.adoc → ...es/ROOT/pages/installation-openshift.adoc b/...ernetes/modules/ROOT/pages/openshift.adoc → ...es/ROOT/pages/installation-openshift.adoc
@@ -1,4 +1,5 @@
-= Deploying on OpenShift
+= Installing on OpenShift
+:page-aliases: openshift.adoc
 :description: Deploy Keycloak on OpenShift with a setup similar to the minikube environment.
 
 {description}

diff --git a/doc/kubernetes/modules/ROOT/pages/prerequisite/prerequisite-helm.adoc b/doc/kubernetes/modules/ROOT/pages/prerequisite/prerequisite-helm.adoc
@@ -3,7 +3,7 @@
 :description: Helm is a pre-requisite to provision applications to Kubernetes.
 
 {description}
-It needs to be installed before the  xref:installation.adoc[] can begin.
+It needs to be installed before the installation can begin.
 
 == Installing Helm
 

diff --git a/doc/kubernetes/modules/ROOT/pages/prerequisite/prerequisite-java.adoc b/doc/kubernetes/modules/ROOT/pages/prerequisite/prerequisite-java.adoc
@@ -3,7 +3,7 @@
 :description: Java 11 or later is a pre-requisite for scripting the automation for Keycloak Benchmark.
 
 {description}
-It needs to be installed before the xref:installation.adoc[] can begin.
+It needs to be installed before the installation can begin.
 
 == Installing Java
 

diff --git a/doc/kubernetes/modules/ROOT/pages/prerequisite/prerequisite-kubectl.adoc b/doc/kubernetes/modules/ROOT/pages/prerequisite/prerequisite-kubectl.adoc
@@ -3,7 +3,7 @@
 :description: Kubectl is a pre-requisite to provision applications to Kubernetes.
 
 {description}
-It needs to be installed before the  xref:installation.adoc[] can begin.
+It needs to be installed before the  installation can begin.
 
 == Installing kubectl
 

diff --git a/doc/kubernetes/modules/ROOT/pages/prerequisite/prerequisite-minikube.adoc b/doc/kubernetes/modules/ROOT/pages/prerequisite/prerequisite-minikube.adoc
@@ -3,7 +3,7 @@
 :description: minikube is a pre-requisite to provision Keycloak on Minikube.
 
 {description}
-It needs to be installed before the  xref:installation.adoc[] can begin.
+It needs to be installed before the installation can begin.
 
 == Installing minikube
 

diff --git a/doc/kubernetes/modules/ROOT/pages/prerequisite/prerequisite-openshift.adoc b/doc/kubernetes/modules/ROOT/pages/prerequisite/prerequisite-openshift.adoc
@@ -3,10 +3,14 @@
 :description: OpenShift is a pre-requisite if the setup is about to be tested on OpenShift.
 
 {description}
-It needs to be completed before xref:openshift.adoc[] can begin.
+It needs to be completed before xref:installation-openshift.adoc[] can begin.
 
 == Prerequisites
 
+This requires a running OpenShift instance, any OpenShift instance should work.
+
+To set up OpenShift on AWS, use xref:prerequisite/prerequisite-rosa.adoc[Red Hat OpenShift Service on AWS (ROSA)].
+
 URL to the console of OpenShift::
 Usually a URL in the form of:
 +

diff --git a/doc/kubernetes/modules/ROOT/pages/prerequisite/prerequisite-rosa.adoc b/doc/kubernetes/modules/ROOT/pages/prerequisite/prerequisite-rosa.adoc
@@ -0,0 +1,118 @@
+= Installing OpenShift on AWS
+:description: OpenShift is a pre-requisite if the setup is about to be tested on OpenShift.
+
+This module is intended to automate tasks around provisioning OpenShift clusters in AWS via ROSA tool, as described in the https://console.redhat.com/openshift/create/rosa/getstarted[ROSA installation guide].
+The scripts are located in the folder `provision/aws` in this repository.
+
+== Prerequisites
+
+. Install the https://aws.amazon.com/cli/[AWS CLI]
+.. Run the commands to install the AWS command line tool:
++
+[source,bash]
+----
+curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
+unzip awscliv2.zip
+sudo ./aws/install
+----
+.. Create Access keys in https://us-east-1.console.aws.amazon.com/iamv2/home?region=us-east-1#/users[AWS Identity and Access Management ]
+... Click on your user account
+... Click on *Security credentials*
+... Click on *Create access key* under *Access keys*
+... Select *Command Line Interface (CLI)*
+... Check the box for *I understand the above recommendation and want to proceed to create an access key*
+... Click *Next*
+... Enter `AWS CLI` as the description tag value and click on *Create access key*
+... Leave the tab open for the next step
+.. Run
++
+----
+aws configure
+----
+
+... AWS Access Key ID: *<copy/paste from above>*
+... AWS Secret Access Key: *<copy/paste from above>*
+... Default region name: *us-east-1*
+... Default output format: <Leave blank>
+.. Test using:
++
+[source,bash]
+----
+aws sts get-caller-identity
+----
+
+. Perform the steps outlined in the https://console.redhat.com/openshift/create/rosa/getstarted[ROSA installation guide]:
+.. Enable ROSA Service in AWS account
+.. Download and install the ROSA command line tool
+.. Create the service linked role for the Elastic Load Balancer
+.. Log in to the ROSA CLI with your Red Hat account token and create AWS account roles and policies
+.. Verify your credentials and quota
+
+== Installation
+
+The installation process is automated in the `rosa_create_cluster.sh` script in the folder `provision/aws` which takes its parameters from environment variables.
+
+It loads environment variables pre-set in `.env` file inside the `aws/` directory.
+
+The script creates the OCP cluster via `rosa create cluster` command, additionally it creates the required operator roles and OIDC provider.
+After the installation process is finished, it creates a new admin user.
+
+.Example `.env` file
+----
+CLUSTER_NAME=rosa-kcb
+ADMIN_PASSWORD=needs-to-have-at-least-14-ascii-characters
+VERSION=4.12.15
+REGION=eu-central-1
+COMPUTE_MACHINE_TYPE=m5.xlarge
+MULTI_AZ=false
+REPLICAS=3
+----
+
+=== Mandatory parameters
+
+`VERSION`:: OCP cluster version.
+`REGION`:: AWS region where the cluster should run.
+`COMPUTE_MACHINE_TYPE`:: https://aws.amazon.com/ec2/instance-types/[AWS instance type] for the default OCP worker machine pool.
+`MULTI_AZ`:: Boolean parameter to indicate whether the OCP cluster should span multiple Availability Zones within the selected region.
+`REPLICAS`:: Number of worker nodes.
+If multi-AZ installation is selected, then this needs to be a multiple of the number of AZs available in the region.
+For example, if the region has 3 AZs, then replicas need to be set to some multiple of 3.
++
+Use the following command to find out about the AZs in the region:
++
+[source,bash,subs=+quotes]
+----
+aws ec2 describe-availability-zones --region _region-name_
+----
+
+=== Optional parameters
+
+`CLUSTER_NAME`:: Name of the cluster.
+If not set, the value of the `$(whoami)` command will be used.
+`ADMIN_PASSWORD`:: Password for the `cluster-admin` user.
+If not set, it will be autogenerated by `rosa create admin`.
+Needs to have at least 14 ASCII characters.
+
+== Finding URLs
+
+To find out about existing clusters and their URLs, use the following commands:
+
+[source,bash,subs=+quotes]
+----
+rosa list clusters
+rosa describe cluster -c _cluster-name_
+----
+
+== Re-create admin user
+
+The above installation script creates an admin user automatically but in case the user needs to re-created it can be done via the `rosa_recreate_admin.sh` script, providing the `CLUSTER_NAME` and optionally `ADMIN_PASSWORD` parameter.
+
+Additionally, an AWS secret named `+${CLUSTER_NAME}-cluster-admin+` will be created via AWS Secrets Manager.
+
+== Uninstallation
+
+The uninstallation is handled by the `rosa_delete_cluster.sh` script.
+
+The only required parameter is `CLUSTER_NAME`.
+
+Additionally, it deletes the cluster's operator roles and OIDC provider, and the admin user.
diff --git a/doc/kubernetes/modules/ROOT/pages/prerequisite/prerequisite-task.adoc b/doc/kubernetes/modules/ROOT/pages/prerequisite/prerequisite-task.adoc
@@ -3,7 +3,7 @@
 :description: Task is a pre-requisite to provision Keycloak Benchmark to Kubernetes.
 
 {description}
-It needs to be installed before the  xref:installation.adoc[] can begin.
+It needs to be installed before the installation can begin.
 
 == Installing task
 

diff --git a/doc/kubernetes/modules/ROOT/pages/prerequisite/prerequisite-yq.adoc b/doc/kubernetes/modules/ROOT/pages/prerequisite/prerequisite-yq.adoc
@@ -3,7 +3,7 @@
 :description: yq is a pre-requisite for scripting the automation for Keycloak Benchmark..
 
 {description}
-It needs to be installed before the  xref:installation.adoc[] can begin.
+It needs to be installed before the installation can begin.
 
 == Installing yq
 

diff --git a/doc/kubernetes/modules/ROOT/pages/util/custom-image-for-keycloak.adoc b/doc/kubernetes/modules/ROOT/pages/util/custom-image-for-keycloak.adoc
@@ -3,7 +3,7 @@
 :description: Use a custom image an external registry or a locally built image and run this in Kubernetes.
 
 {description}
-A running version of xref:installation.adoc[Keycloak within Minikube] is a prerequisite.
+A running version of xref:installation-minikube.adoc[Keycloak on Minikube] or xref:installation-openshift.adoc[Keycloak on OpenShift] is a prerequisite.
 
 == Overview
 

diff --git a/doc/kubernetes/modules/ROOT/pages/util/debugging-keycloak.adoc b/doc/kubernetes/modules/ROOT/pages/util/debugging-keycloak.adoc
@@ -2,7 +2,7 @@
 :description: Analyze problems during development by connecting a debugger on the local machine to Keycloak inside minikube.
 
 {description}
-A running version of xref:installation.adoc[Keycloak within Minikube] is a prerequisite.
+A running version of xref:installation-minikube.adoc[Keycloak within Minikube] is a prerequisite.
 
 == Overview
 
@@ -17,7 +17,7 @@ image::util/minikube-runtime-view-debug-keycloak.dio.svg[]
 
 Prerequisite:
 
-. xref:installation.adoc[Keycloak installed and running on Minikube]
+. xref:installation-minikube.adoc[Keycloak installed and running on Minikube]
 
 . Java IDE on the local machine with either a checked-out Keycloak repository matching the deployed version of Keycloak to debug Keycloak, or a checked-out repository of a provider installed into Keycloak that the developer wants to debug.
 

diff --git a/provision/aws/README.adoc b/provision/aws/README.adoc
@@ -1,66 +1 @@
-= AWS provisioning module
-
-This module is intended to automate tasks around provisioning OpenShift clusters in AWS via ROSA tool,
-as described in the ROSA installation guide: https://console.redhat.com/openshift/create/rosa/getstarted
-
-== Prerequisities
-
-. Enable ROSA Service in AWS account - *MANUAL STEP*
-. Download and install the ROSA and AWS command line tools - *MANUAL STEP*
-. Create the service linked role for the Elastic Load Balancer
-. Log in to the ROSA CLI with your Red Hat account token and create AWS account roles and policies - *MANUAL STEP*
-. Verify your credentials and quota
-
-== Installation
-
-The installation process is automated in the `rosa_create_cluster.sh` script
-which takes its parameters from environment variables.
-
-It will load environment variables pre-set in `.env` file inside the `aws/` directory.
-
-The script will create the OCP cluster via `rosa create cluster` command, 
-additionally it will create the required operator roles and OIDC provider.
-After the installation process is finished it will create a new admin user.
-
-=== Optional parameters:
-- `CLUSTER_NAME` - Name of the cluster. If not set, the value of `$(whoami)` command will be used.
-- `ADMIN_PASSWORD` - Password for the `cluster-admin` user. If not set, it will be autogenerated by `rosa create admin`.
-
-=== Mandatory parameters:
-- `VERSION` - OCP cluster version.
-- `REGION` - AWS region where the cluster should run.
-- `COMPUTE_MACHINE_TYPE` - https://aws.amazon.com/ec2/instance-types/[AWS instance type] for the default OCP worker machine pool.
-- `MULTI_AZ` - Boolean parameter to indicate whether the OCP cluster should span multiple Availability Zones within the selected region.
-- `REPLICAS` - Number of worker nodes. If multi-AZ installation is selected then this needs to be a multiple 
-of the number of AZs available in the region. For example if the region has 3 AZs, then replicas need to be set to some multiple of 3.
-
-=== Example `.env` file
-[source,bash]
-----
-CLUSTER_NAME=rosa-kcb
-ADMIN_PASSWORD=needs-to-have-at-least-14-ascii-characters
-VERSION=4.12.15
-REGION=eu-central-1
-COMPUTE_MACHINE_TYPE=m5.xlarge
-MULTI_AZ=false
-REPLICAS=3
-----
-
-
-== Re-create admin user
-
-The above installation script will create an admin user automatically but in case
-the user needs to re-created it can be done via the `rosa_recreate_admin.sh` script, 
-providing the `CLUSTER_NAME` and optionally `ADMIN_PASSWORD` parameter.
-
-Additionally, an AWS secret named `${CLUSTER_NAME}-cluster-admin` will be created via AWS Secrets Manager.
-
-
-== Uninstallation
-
-The uninstallation is handled by the `rosa_delete_cluster.sh` script.
-
-The only required parameter is `CLUSTER_NAME`.
-
-Additionally it will delete cluster's operator roles and OIDC provider, 
-and the admin user.
+See https://www.keycloak.org/keycloak-benchmark/kubernetes-guide/latest/prerequisite/prerequisite-rosa[Installing OpenShift on AWS] on how to use these scripts.