Merge pull request #119 from chirangaalwis/kubernetes-apim-fix-q2-mer…

…ge-conflicts Merge 2.5.x branch to master branch
wso2 · Jul 15, 2018 · f05d96e · f05d96e
2 parents b46f995 + 234dd1e
commit f05d96e
Show file tree

Hide file tree

Showing 164 changed files with 26,810 additions and 581 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,122 @@
-# Kubernetes Resources for WSO2 API Manager
-*Kubernetes Resources for container-based deployments of WSO2 API Manager deployment patterns*
+# Kubernetes and Helm Resources for WSO2 API Manager
+*Kubernetes and Helm Resources for container-based deployments of WSO2 API Manager deployment patterns*
 
-This repository contains Kubernetes resources required for,
+This repository contains Kubernetes and Helm resources required for,
 
-* [WSO2 API Manager pattern 1](pattern-1)
+* WSO2 API Manager pattern 1
 
-* [WSO2 API Manager pattern 2](pattern-2)
+* WSO2 API Manager pattern 2
+
+## Deploy Kubernetes resources
+
+In order to deploy Kubernetes resources for each deployment pattern, follow the **Quick Start Guide**s for each deployment pattern
+given below:
+
+* [WSO2 API Manager pattern 1](pattern-1/README.md)
+
+* [WSO2 API Manager pattern 2](pattern-2/README.md)
+
+## Deploy Helm resources
+
+In order to deploy Helm resources for each deployment pattern, follow the **Quick Start Guide**s for each deployment pattern
+given below:
+
+* [WSO2 API Manager pattern 1](helm/pattern-1/README.md)
+
+* [WSO2 API Manager pattern 2](helm/pattern-2/README.md)
+
+## How to update configurations
+
+Kubernetes resources for WSO2 products use Kubernetes [ConfigMaps](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/)
+to pass on the minimum set of configurations required to setup a product deployment pattern.
+
+For example, the minimum set of configurations required to setup pattern 1 of WSO2 API Manager can be found
+in `<KUBERNETES_HOME>/pattern-1/confs` directory. The Kubernetes ConfigMaps are generated from these files.
+
+If you intend to pass on any additional files with configuration changes, third-party libraries, OSGi bundles and security
+related artifacts to the Kubernetes cluster, you may mount the desired content to `/home/wso2carbon/wso2-server-volume` directory path within
+a WSO2 product Docker container.
+
+The following example depicts how this can be achieved when passing additional configurations to WSO2 API Manager in pattern 1 of WSO2 API Manager:
+
+a. In order to apply the updated configurations, WSO2 product server instances need to be restarted. Hence, un-deploy all the Kubernetes resources
+corresponding to the product deployment, if they are already deployed.
+
+b. Create and export a directory within the NFS server instance.
+
+c. Add the additional configuration files, third-party libraries, OSGi bundles and security related artifacts, into appropriate
+folders matching that of the relevant WSO2 product home folder structure, within the previously created directory.
+
+d. Grant ownership to `wso2carbon` user and `wso2` group, for the directory created in step (b).
+
+   ```
+   sudo chown -R wso2carbon:wso2 <directory_name>
+   ```
+      
+e. Grant read-write-execute permissions to the `wso2carbon` user, for the directory created in step (b).
+
+   ```
+   chmod -R 700 <directory_name>
+   ```
+
+f. Map the directory created in step (b) to a Kubernetes [Persistent Volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)
+in the `<KUBERNETES_HOME>/pattern-1/volumes/persistent-volumes.yaml` file. For example, append the following entry to the file:
+
+```
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: wso2apim-with-analytics-additional-config-pv
+  labels:
+    purpose: apim-additional-configs
+spec:
+  capacity:
+    storage: 1Gi
+  accessModes:
+    - ReadWriteMany
+  persistentVolumeReclaimPolicy: Retain
+  nfs:
+    server: <NFS_SERVER_IP>
+    path: "<NFS_LOCATION_PATH>"
+```
+
+Provide the appropriate `NFS_SERVER_IP` and `NFS_LOCATION_PATH`.
+
+g. Create a Kubernetes Persistent Volume Claim to bind with the Kubernetes Persistent Volume created in step e. For example, append the following entry
+to the file `<KUBERNETES_HOME>/pattern-1/apim/wso2apim-volume-claim.yaml`:
+
+```
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: wso2apim-with-analytics-additional-config-volume-claim
+spec:
+  accessModes:
+    - ReadWriteMany
+  resources:
+    requests:
+      storage: 1Gi
+  storageClassName: ""
+  selector:
+    matchLabels:
+      purpose: apim-additional-configs
+```
+
+h. Update the appropriate Kubernetes [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) resource(s).
+For example in the discussed scenario, update the volumes (`spec.template.spec.volumes`) and volume mounts (`spec.template.spec.containers[wso2apim-with-analytics-apim-worker].volumeMounts`) in
+`<KUBERNETES_HOME>/pattern-1/apim/wso2apim-deployment.yaml` file as follows:
+
+```
+volumeMounts:
+...
+- name: wso2apim-with-analytics-additional-config-storage-volume
+  mountPath: "/home/wso2carbon/wso2-server-volume"
+
+volumes:
+...
+- name: wso2apim-with-analytics-additional-config-storage-volume
+  persistentVolumeClaim:
+    claimName: wso2apim-with-analytics-additional-config-volume-claim
+```
+
+i. Deploy the Kubernetes resources as defined in section **Quick Start Guide** for the pattern 1 of WSO2 API Manager.
diff --git a/helm/pattern-1/README.md b/helm/pattern-1/README.md
@@ -0,0 +1,140 @@
+# Helm Chart for deployment of WSO2 API Manager with WSO2 API Manager Analytics
+
+## Contents
+
+* [Prerequisites](#prerequisites)
+* [Quick Start Guide](#quick-start-guide)
+
+## Prerequisites
+
+* In order to use WSO2 Helm resources, you need an active WSO2 subscription. If you do not possess an active WSO2
+  subscription already, you can sign up for a WSO2 Free Trial Subscription from [here](https://wso2.com/free-trial-subscription).<br><br>
+
+* Install [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), [Helm](https://github.com/kubernetes/helm/blob/master/docs/install.md)
+(and Tiller) and [Kubernetes client](https://kubernetes.io/docs/tasks/tools/install-kubectl/) (compatible with v1.10) in order to run the 
+steps provided in the following quick start guide.<br><br>
+
+* An already setup [Kubernetes cluster](https://kubernetes.io/docs/setup/pick-right-solution/).<br><br>
+
+* Install [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/deploy/). This can be easily done via
+
+  ```
+  helm install stable/nginx-ingress --name nginx-wso2apim-analytics --set rbac.create=true
+  ```
+
+* A pre-configured Network File System (NFS) to be used as the persistent volume for artifact sharing and persistence.
+In the NFS server instance, create a Linux system user account named `wso2carbon` with user id `802` and a system group named `wso2` with group id `802`.
+Add the `wso2carbon` user to the group `wso2`.
+
+  ```
+   groupadd --system -g 802 wso2
+   useradd --system -g 802 -u 802 wso2carbon
+  ```
+
+## Quick Start Guide    
+
+>In the context of this document, <br>
+>* `KUBERNETES_HOME` will refer to a local copy of the [`wso2/kubernetes-apim`](https://github.com/wso2/kubernetes-apim/)
+Git repository. <br>
+>* `HELM_HOME` will refer to `<KUBERNETES_HOME>/helm/pattern-1`. <br>
+
+##### 1. Clone Kubernetes Resources for WSO2 API Manager Git repository.
+
+```
+git clone https://github.com/wso2/kubernetes-apim.git
+```
+
+##### 2. Setup a Network File System (NFS) to be used for persistent storage.
+
+Create and export unique directories within the NFS server instance for each of the following Kubernetes Persistent Volume
+resources defined in the `<HELM_HOME>/apim-with-analytics-conf/values.yaml` file:
+
+* `sharedDeploymentLocationPath`
+* `analyticsDataLocationPath`
+* `analyticsLocationPath`
+
+Grant ownership to `wso2carbon` user and `wso2` group, for each of the previously created directories.
+
+  ```
+  sudo chown -R wso2carbon:wso2 <directory_name>
+  ```
+
+Grant read-write-execute permissions to the `wso2carbon` user, for each of the previously created directories.
+
+  ```
+  chmod -R 700 <directory_name>
+  ```
+
+##### 3. Provide configurations.
+
+a. The default product configurations are available at `<HELM_HOME>/apim-with-analytics-conf/confs` folder. Change the 
+configurations as necessary.
+
+b. Open the `<HELM_HOME>/apim-with-analytics-conf/values.yaml` and provide the following values.
+
+| Parameter                       | Description                                                                               |
+|---------------------------------|-------------------------------------------------------------------------------------------|
+| `username`                      | Your WSO2 username                                                                        |
+| `password`                      | Your WSO2 password                                                                        |
+| `email`                         | Docker email                                                                              |
+| `namespace`                     | Kubernetes Namespace in which the resources are deployed                                  |
+| `svcaccount`                    | Kubernetes Service Account in the `namespace` to which product instance pods are attached |
+| `serverIp`                      | NFS Server IP                                                                             |
+| `sharedDeploymentLocationPath`  | NFS shared deployment directory (`<APIM_HOME>/repository/deployment`) location for APIM   |
+| `analyticsDataLocationPath`     | NFS volume for Indexed data for Analytics (`<DAS_HOME>/repository/data`)                  |
+| `analyticsLocationPath`         | NFS volume for Analytics data for Analytics(`<DAS_HOME>/repository/analytics`)            |
+
+c. Open the `<HELM_HOME>/apim-with-analytics-deployment/values.yaml` and provide the following values. 
+
+| Parameter                       | Description                                                                               |
+|---------------------------------|-------------------------------------------------------------------------------------------|
+| `namespace`                     | Kubernetes Namespace in which the resources are deployed                                  |
+| `svcaccount`                    | Kubernetes Service Account in the `namespace` to which product instance pods are attached |
+
+##### 4. Deploy the configurations.
+
+```
+helm install --name <RELEASE_NAME> <HELM_HOME>/apim-with-analytics-conf
+```
+
+##### 5. Deploy product database(s) using MySQL in Kubernetes.
+
+```
+helm install --name wso2apim-with-analytics-rdbms-service -f <HELM_HOME>/mysql/values.yaml stable/mysql --namespace <NAMESPACE>
+```
+
+NAMESPACE should be same as in `step 3.b`.
+
+For a serious deployment (e.g. production grade setup), it is recommended to connect product instances to a user owned and managed RDBMS instance.
+
+##### 6. Deploy WSO2 API Manager with Analytics.
+
+```
+helm install --name <RELEASE_NAME> <HELM_HOME>/apim-with-analytics-deployment
+```
+
+##### 7. Access Management Console:
+
+a. Obtain the external IP (`EXTERNAL-IP`) of the Ingress resources by listing down the Kubernetes Ingresses.
+
+  ```
+  kubectl get ing
+  ```
+
+e.g.
+
+```
+NAME                                             HOSTS                       ADDRESS         PORTS     AGE
+wso2apim-with-analytics-apim-analytics-ingress   wso2apim-analytics          <EXTERNAL-IP>   80, 443   6m
+wso2apim-with-analytics-apim-ingress             wso2apim,wso2apim-gateway   <EXTERNAL-IP>   80, 443   7m
+```
+
+b. Add the above host as an entry in /etc/hosts file as follows:
+
+  ```
+  <EXTERNAL-IP>	wso2apim-analytics
+  <EXTERNAL-IP>	wso2apim
+  <EXTERNAL-IP>	wso2apim-gateway
+  ```
+
+c. Try navigating to `https://wso2apim/carbon` and `https://wso2apim-analytics/carbon` from your favorite browser.
diff --git a/helm/pattern-1/apim-with-analytics-conf/Chart.yaml b/helm/pattern-1/apim-with-analytics-conf/Chart.yaml
@@ -0,0 +1,19 @@
+# Copyright (c) 2018, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+apiVersion: v1
+appVersion: "1.0"
+description: A Helm chart for the deployment of WSO2 APIM-Analytics configurations
+name: scalable-is-conf
+version: 1.0.0
diff --git a/helm/pattern-1/apim-with-analytics-conf/auth.json b/helm/pattern-1/apim-with-analytics-conf/auth.json
@@ -0,0 +1,10 @@
+{
+	"auths": {
+		"docker.wso2.com": {
+			"username": "docker.wso2.com.username",
+			"password": "docker.wso2.com.password",
+			"email": "docker.wso2.com.email",
+			"auth": "docker.wso2.com.auth"
+		}
+	}
+}