From 8ed755660ec196c3ff76d8d55573f77ae6e6fe92 Mon Sep 17 00:00:00 2001 From: chirangaalwis Date: Mon, 2 Jul 2018 17:28:37 +0530 Subject: [PATCH] Upgrade README.md documentation --- is-with-analytics/README.md | 27 ++++++++---- is-with-analytics/scripts/README.md | 68 ++++++++++++++++++++++------- is/README.md | 27 ++++++++---- is/scripts/README.md | 62 +++++++++++++++++++------- 4 files changed, 135 insertions(+), 49 deletions(-) diff --git a/is-with-analytics/README.md b/is-with-analytics/README.md index a2a35efe..9a61801e 100644 --- a/is-with-analytics/README.md +++ b/is-with-analytics/README.md @@ -20,7 +20,7 @@ in order to run the steps provided
in the following quick start guide.

In the context of this document, `KUBERNETES_HOME` will refer to a local copy of the [`wso2/kubernetes-is`](https://github.com/wso2/kubernetes-is/) Git repository.
-##### 1. Checkout Kubernetes Resources for WSO2 Identity Server Git repository: +##### 1. Clone the Kubernetes Resources for WSO2 Identity Server Git repository: ``` git clone https://github.com/wso2/kubernetes-is.git @@ -53,7 +53,7 @@ kubectl create secret docker-registry wso2creds --docker-server=docker.wso2.com Please see [Kubernetes official documentation](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-secret-in-the-cluster-that-holds-your-authorization-token) for further details. -##### 4. Setup and configure external product database(s): +##### 4. Setup product database(s): Setup the external product databases. Please refer to WSO2 Identity Server's [official documentation](https://docs.wso2.com/display/IS560/Setting+Up+Separate+Databases+for+Clustering) on creating the required databases for the deployment. @@ -85,7 +85,7 @@ Please refer WSO2's [official documentation](https://docs.wso2.com/display/ADMIN ``` Setup a Network File System (NFS) to be used as the persistent volume for persisting MySQL DB data. - Provide read-write-executable permissions to `other` users, for the folder `NFS_LOCATION_PATH`. + Provide read-write-execute permissions to `other` users, for the folder `NFS_LOCATION_PATH`. Update the NFS server IP (`NFS_SERVER_IP`) and export path (`NFS_LOCATION_PATH`) of persistent volume resource named `wso2is-with-analytics-mysql-pv` in the file `/is-with-analytics/extras/rdbms/volumes/persistent-volumes.yaml`. @@ -113,7 +113,8 @@ kubectl create --username=admin --password= -f /is-with-analytics/volumes/persistent-volumes.yaml` file. * `wso2is-with-analytics-shared-deployment-pv` * `wso2is-with-analytics-shared-tenants-pv` @@ -122,13 +123,21 @@ Update the NFS server IP (`NFS_SERVER_IP`) and export path (`NFS_LOCATION_PATH`) * `wso2is-with-analytics-is-analytics-pv-1` * `wso2is-with-analytics-is-analytics-pv-2` -in `/is-with-analytics/volumes/persistent-volumes.yaml` file. - -Create a user named `wso2carbon` with user id `802` and a group named `wso2` with group id `802` in the NFS node. +Create a Linux system user account named `wso2carbon` with user id `802` and a system group named `wso2` with group id `802` in the NFS node. Add `wso2carbon` user to the group `wso2`. -Then, provide ownership of the exported folder `NFS_LOCATION_PATH` (used for artifact sharing) to `wso2carbon` user and `wso2` group. -And provide read-write-executable permissions to owning `wso2carbon` user, for the folder `NFS_LOCATION_PATH`. +``` +groupadd --system -g 802 wso2 +useradd --system -g 802 -u 802 wso2carbon +``` + +Then, grant ownership of the exported folder `NFS_LOCATION_PATH` (used for artifact sharing) to `wso2carbon` user and `wso2` group. +And grant read-write-execute permissions to owning `wso2carbon` user, for the folder `NFS_LOCATION_PATH`. + +``` +sudo chown -R wso2carbon:wso2 NFS_LOCATION_PATH +chmod -R 700 NFS_LOCATION_PATH +``` Then, deploy the persistent volume resource and volume claim as follows: diff --git a/is-with-analytics/scripts/README.md b/is-with-analytics/scripts/README.md index d5b09819..8c97dfe4 100644 --- a/is-with-analytics/scripts/README.md +++ b/is-with-analytics/scripts/README.md @@ -19,7 +19,7 @@ in order to run the steps provided
in the following quick start guide.

In the context of this document, `KUBERNETES_HOME` will refer to a local copy of the [`wso2/kubernetes-is`](https://github.com/wso2/kubernetes-is/) Git repository.
-##### 1. Checkout Kubernetes Resources for WSO2 Identity Server Git repository: +##### 1. Clone the Kubernetes Resources for WSO2 Identity Server Git repository: ``` git clone https://github.com/wso2/kubernetes-is.git @@ -34,7 +34,8 @@ please refer the official documentation, [NGINX Ingress Controller Installation ##### 3. Setup a Network File System (NFS) to be used as the persistent volume for artifact sharing across Identity Server and Analytics instances. -Update the NFS server IP (`NFS_SERVER_IP`) and export path (`NFS_LOCATION_PATH`) of persistent volume resources, +Update the NFS server IP (`NFS_SERVER_IP`) and export path (`NFS_LOCATION_PATH`) of the following persistent volume resources +defined in the `/is-with-analytics/volumes/persistent-volumes.yaml` file. * `wso2is-with-analytics-shared-deployment-pv` * `wso2is-with-analytics-shared-tenants-pv` @@ -43,25 +44,60 @@ Update the NFS server IP (`NFS_SERVER_IP`) and export path (`NFS_LOCATION_PATH`) * `wso2is-with-analytics-is-analytics-data-pv-1` * `wso2is-with-analytics-is-analytics-data-pv-2` -in `/is-with-analytics/volumes/persistent-volumes.yaml` file. - -Create a user named `wso2carbon` with user id `802` and a group named `wso2` with group id `802` in the NFS node. +Create a Linux system user account named `wso2carbon` with user id `802` and a system group named `wso2` with group id `802` in the NFS node. Add `wso2carbon` user to the group `wso2`. -Then, provide ownership of the exported folder `NFS_LOCATION_PATH` (used for artifact sharing) to `wso2carbon` user and `wso2` group. -And provide read-write-executable permissions to owning `wso2carbon` user, for the folder `NFS_LOCATION_PATH`. +``` +groupadd --system -g 802 wso2 +useradd --system -g 802 -u 802 wso2carbon +``` + +Then, grant ownership of the exported folder `NFS_LOCATION_PATH` (used for artifact sharing) to `wso2carbon` user and `wso2` group. +And grant read-write-execute permissions to owning `wso2carbon` user, for the folder `NFS_LOCATION_PATH`. + +``` +sudo chown -R wso2carbon:wso2 NFS_LOCATION_PATH +chmod -R 700 NFS_LOCATION_PATH +``` + +##### 4. Setup product database(s): + +For **evaluation purposes**, + +* You can use Kubernetes resources provided in the directory `KUBERNETES_HOME/is-with-analytics/extras/rdbms/mysql` +for deploying the product databases, using MySQL in Kubernetes. However, this approach of product database deployment is +**not recommended** for a production setup. + +* For using these Kubernetes resources, + + Setup a Network File System (NFS) to be used as the persistent volume for persisting MySQL DB data. + Provide read-write-execute permissions to `other` users, for the folder `NFS_LOCATION_PATH`. + Update the NFS server IP (`NFS_SERVER_IP`) and export path (`NFS_LOCATION_PATH`) of persistent volume resource + named `wso2is-with-analytics-mysql-pv` in the file `/is-with-analytics/extras/rdbms/volumes/persistent-volumes.yaml`. + +In a **production grade setup**, -Finally, setup a Network File System (NFS) to be used as the persistent volume for persisting MySQL DB data. -Provide read-write-executable permissions to `other` users, for the folder `NFS_LOCATION_PATH`. -Update the NFS server IP (`NFS_SERVER_IP`) and export path (`NFS_LOCATION_PATH`) of persistent volume resource -named `wso2is-with-analytics-mysql-pv` in the file `/is-with-analytics/extras/rdbms/volumes/persistent-volumes.yaml`. +* Setup the external product databases. Please refer to WSO2 Identity Server's [official documentation](https://docs.wso2.com/display/IS560/Setting+Up+Separate+Databases+for+Clustering) + on creating the required databases for the deployment. + + Provide appropriate connection URLs, corresponding to the created external databases and the relevant driver class names for the data sources defined in + the following files: + + * `KUBERNETES_HOME/is-with-analytics/confs/is/datasources/master-datasources.xml` + * `KUBERNETES_HOME/is-with-analytics/confs/is/datasources/bps-datasources.xml` + * `KUBERNETES_HOME/is-with-analytics/confs/is-analytics-1/datasources/master-datasources.xml` + * `KUBERNETES_HOME/is-with-analytics/confs/is-analytics-1/datasources/analytics-datasources.xml` + * `KUBERNETES_HOME/is-with-analytics/confs/is-analytics-2/datasources/master-datasources.xml` + * `KUBERNETES_HOME/is-with-analytics/confs/is-analytics-2/datasources/analytics-datasources.xml` + + Please refer WSO2's [official documentation](https://docs.wso2.com/display/ADMIN44x/Configuring+master-datasources.xml) on configuring data sources. -##### 4. Deploy Kubernetes resources: +##### 5. Deploy Kubernetes resources: Change directory to `KUBERNETES_HOME/is-with-analytics/scripts` and execute the `deploy.sh` shell script on the terminal, with the appropriate configurations as follows: ``` -./deploy.sh --wso2-subscription-username= --wso2-subscription-password= --cluster-admin-password= +./deploy.sh --wso2-username= --wso2-password= --cluster-admin-password= ``` * A Kubernetes Secret named `wso2creds` in the cluster to authenticate with the [`WSO2 Docker Registry`](https://docker.wso2.com), to pull the required images. @@ -76,7 +112,7 @@ The following details need to be replaced in the relevant command. >To un-deploy, be on the same directory and execute the `undeploy.sh` shell script on the terminal. -##### 5. Access Management Consoles: +##### 6. Access Management Consoles: Default deployment will expose `wso2is` and `wso2is-analytics` hosts (to expose Administrative services and Management Console). @@ -101,13 +137,13 @@ wso2is-with-analytics-is-ingress wso2is 3. Try navigating to `https://wso2is/carbon` and `https://wso2is-analytics/carbon` from your favorite browser. -##### 6. Scale up using `kubectl scale`: +##### 7. Scale up using `kubectl scale`: Default deployment runs two replicas (or pods) of WSO2 Identity server. To scale this deployment into any `` number of container replicas, upon your requirement, simply run following Kubernetes client command on the terminal. ``` -kubectl scale --replicas= -f /is/identity-server-deployment.yaml +kubectl scale --replicas= -f /is-with-analytics/is/identity-server-deployment.yaml ``` For example, If `` is 2, you are here scaling up this deployment from 1 to 2 container replicas. diff --git a/is/README.md b/is/README.md index e1047682..a58616cc 100644 --- a/is/README.md +++ b/is/README.md @@ -20,7 +20,7 @@ in order to run the steps provided
in the following quick start guide.

In the context of this document, `KUBERNETES_HOME` will refer to a local copy of the [`wso2/kubernetes-is`](https://github.com/wso2/kubernetes-is/) Git repository.
-##### 1. Checkout Kubernetes Resources for WSO2 Identity Server Git repository: +##### 1. Clone the Kubernetes Resources for WSO2 Identity Server Git repository: ``` git clone https://github.com/wso2/kubernetes-is.git @@ -53,7 +53,7 @@ kubectl create secret docker-registry wso2creds --docker-server=docker.wso2.com Please see [Kubernetes official documentation](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-secret-in-the-cluster-that-holds-your-authorization-token) for further details. -##### 4. Setup and configure external product database(s): +##### 4. Setup product database(s): Setup the external product databases. Please refer to WSO2 Identity Server's [official documentation](https://docs.wso2.com/display/IS560/Setting+Up+Separate+Databases+for+Clustering) on creating the required databases for the deployment. @@ -81,7 +81,7 @@ Please refer WSO2's [official documentation](https://docs.wso2.com/display/ADMIN ``` Setup a Network File System (NFS) to be used as the persistent volume for persisting MySQL DB data. - Provide read-write-executable permissions to `other` users, for the folder `NFS_LOCATION_PATH`. + Provide read-write-execute permissions to `other` users, for the folder `NFS_LOCATION_PATH`. Update the NFS server IP (`NFS_SERVER_IP`) and export path (`NFS_LOCATION_PATH`) of persistent volume resource named `wso2is-mysql-pv` in the file `/is/extras/rdbms/volumes/persistent-volumes.yaml`. @@ -109,18 +109,27 @@ kubectl create --username=admin --password= -f /is/volumes/persistent-volumes.yaml` file. * `wso2is-shared-deployment-pv` * `wso2is-shared-tenants-pv` -in `/is/volumes/persistent-volumes.yaml` file. - -Create a user named `wso2carbon` with user id `802` and a group named `wso2` with group id `802` in the NFS node. +Create a Linux system user account named `wso2carbon` with user id `802` and a system group named `wso2` with group id `802` in the NFS node. Add `wso2carbon` user to the group `wso2`. -Then, provide ownership of the exported folder `NFS_LOCATION_PATH` (used for artifact sharing) to `wso2carbon` user and `wso2` group. -And provide read-write-executable permissions to owning `wso2carbon` user, for the folder `NFS_LOCATION_PATH`. +``` +groupadd --system -g 802 wso2 +useradd --system -g 802 -u 802 wso2carbon +``` + +Then, grant ownership of the exported folder `NFS_LOCATION_PATH` (used for artifact sharing) to `wso2carbon` user and `wso2` group. +And grant read-write-execute permissions to owning `wso2carbon` user, for the folder `NFS_LOCATION_PATH`. + +``` +sudo chown -R wso2carbon:wso2 NFS_LOCATION_PATH +chmod -R 700 NFS_LOCATION_PATH +``` Then, deploy the persistent volume resource and volume claim as follows: diff --git a/is/scripts/README.md b/is/scripts/README.md index a1d45887..03ccd375 100644 --- a/is/scripts/README.md +++ b/is/scripts/README.md @@ -19,7 +19,7 @@ in order to run the steps provided
in the following quick start guide.

In the context of this document, `KUBERNETES_HOME` will refer to a local copy of the [`wso2/kubernetes-is`](https://github.com/wso2/kubernetes-is/) Git repository.
-##### 1. Checkout Kubernetes Resources for WSO2 Identity Server Git repository: +##### 1. Clone the Kubernetes Resources for WSO2 Identity Server Git repository: ``` git clone https://github.com/wso2/kubernetes-is.git @@ -34,30 +34,62 @@ please refer the official documentation, [NGINX Ingress Controller Installation ##### 3. Setup a Network File System (NFS) to be used as the persistent volume for artifact sharing across Identity Server and Analytics instances. -Update the NFS server IP (`NFS_SERVER_IP`) and export path (`NFS_LOCATION_PATH`) of persistent volume resources, +Update the NFS server IP (`NFS_SERVER_IP`) and export path (`NFS_LOCATION_PATH`) of the following persistent volume resources +defined in the `/is/volumes/persistent-volumes.yaml` file. * `wso2is-shared-deployment-pv` * `wso2is-shared-tenants-pv` -in `/is/volumes/persistent-volumes.yaml` file. - -Create a user named `wso2carbon` with user id `802` and a group named `wso2` with group id `802` in the NFS node. +Create a Linux system user account named `wso2carbon` with user id `802` and a system group named `wso2` with group id `802` in the NFS node. Add `wso2carbon` user to the group `wso2`. -Then, provide ownership of the exported folder `NFS_LOCATION_PATH` (used for artifact sharing) to `wso2carbon` user and `wso2` group. -And provide read-write-executable permissions to owning `wso2carbon` user, for the folder `NFS_LOCATION_PATH`. +``` +groupadd --system -g 802 wso2 +useradd --system -g 802 -u 802 wso2carbon +``` + +Then, grant ownership of the exported folder `NFS_LOCATION_PATH` (used for artifact sharing) to `wso2carbon` user and `wso2` group. +And grant read-write-execute permissions to owning `wso2carbon` user, for the folder `NFS_LOCATION_PATH`. + +``` +sudo chown -R wso2carbon:wso2 NFS_LOCATION_PATH +chmod -R 700 NFS_LOCATION_PATH +``` + +##### 4. Setup product database(s): -Finally, setup a Network File System (NFS) to be used as the persistent volume for persisting MySQL DB data. -Provide read-write-executable permissions to `other` users, for the folder `NFS_LOCATION_PATH`. -Update the NFS server IP (`NFS_SERVER_IP`) and export path (`NFS_LOCATION_PATH`) of persistent volume resource -named `wso2is-mysql-pv` in the file `/is/extras/rdbms/volumes/persistent-volumes.yaml`. +For **evaluation purposes**, + +* You can use Kubernetes resources provided in the directory `KUBERNETES_HOME/is/extras/rdbms/mysql` +for deploying the product databases, using MySQL in Kubernetes. However, this approach of product database deployment is +**not recommended** for a production setup. + +* For using these Kubernetes resources, + + Setup a Network File System (NFS) to be used as the persistent volume for persisting MySQL DB data. + Provide read-write-execute permissions to `other` users, for the folder `NFS_LOCATION_PATH`. + Update the NFS server IP (`NFS_SERVER_IP`) and export path (`NFS_LOCATION_PATH`) of persistent volume resource + named `wso2is-mysql-pv` in the file `/is/extras/rdbms/volumes/persistent-volumes.yaml`. + +In a **production grade setup**, + +* Setup the external product databases. Please refer to WSO2 Identity Server's [official documentation](https://docs.wso2.com/display/IS560/Setting+Up+Separate+Databases+for+Clustering) + on creating the required databases for the deployment. + + Provide appropriate connection URLs, corresponding to the created external databases and the relevant driver class names for the data sources defined in + the following files: + + * `KUBERNETES_HOME/is/confs/is/datasources/master-datasources.xml` + * `KUBERNETES_HOME/is/confs/is/datasources/bps-datasources.xml` + + Please refer WSO2's [official documentation](https://docs.wso2.com/display/ADMIN44x/Configuring+master-datasources.xml) on configuring data sources. -##### 4. Deploy Kubernetes resources: +##### 5. Deploy Kubernetes resources: Change directory to `KUBERNETES_HOME/is/scripts` and execute the `deploy.sh` shell script on the terminal, with the appropriate configurations as follows: ``` -./deploy.sh --wso2-subscription-username= --wso2-subscription-password= --cluster-admin-password= +./deploy.sh --wso2-username= --wso2-password= --cluster-admin-password= ``` * A Kubernetes Secret named `wso2creds` in the cluster to authenticate with the [`WSO2 Docker Registry`](https://docker.wso2.com), to pull the required images. @@ -72,7 +104,7 @@ The following details need to be replaced in the relevant command. >To un-deploy, be on the same directory and execute the `undeploy.sh` shell script on the terminal. -##### 5. Access Management Console: +##### 6. Access Management Console: Default deployment will expose `wso2is` host (to expose Administrative services and Management Console). @@ -95,7 +127,7 @@ wso2is-ingress wso2is 80, 443 3m 3. Try navigating to `https://wso2is/carbon` from your favorite browser. -##### 6. Scale up using `kubectl scale`: +##### 7. Scale up using `kubectl scale`: Default deployment runs a single replica (or pod) of WSO2 Identity server. To scale this deployment into any `` number of container replicas, upon your requirement, simply run following Kubernetes client command on the terminal.