From 46a5c1ee199bb728434b353694d237dd5725e938 Mon Sep 17 00:00:00 2001 From: Chiranga Alwis Date: Thu, 19 Mar 2020 16:29:43 +0530 Subject: [PATCH] Update README documentation and change log --- CHANGELOG.md | 9 +++ README.md | 19 +------ advanced/ManageArtifacts.md | 95 -------------------------------- advanced/ManageConfigurations.md | 86 ----------------------------- advanced/am-pattern-1/README.md | 12 +++- advanced/am-pattern-2/README.md | 12 +++- advanced/am-pattern-3/README.md | 12 +++- 7 files changed, 37 insertions(+), 208 deletions(-) delete mode 100644 advanced/ManageArtifacts.md delete mode 100644 advanced/ManageConfigurations.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b84cc91..b2ee3595 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,15 @@ All notable changes to this project 3.0.x per each release will be documented in The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) +## [v3.0.0.4] - 2020-03-19 + +### Added +- Add Helm resources for WSO2 API Management deployment pattern 2. +- Add Helm resources for WSO2 API Management deployment pattern 3. + +For detailed information on the tasks carried out during this release, please see the GitHub milestones +[v3.0.0.4](https://github.com/wso2/kubernetes-apim/milestone/9). + ## [v3.0.0.3] - 2020-01-06 ### Added diff --git a/README.md b/README.md index 7d997796..ea741b9e 100644 --- a/README.md +++ b/README.md @@ -16,23 +16,6 @@ * [Deployment Pattern 2](advanced/am-pattern-2/README.md) * [Deployment Pattern 3](advanced/am-pattern-3/README.md) -## Advanced topics - -* [Update product configurations](advanced/ManageConfigurations.md) -* [Introduce additional artifacts](advanced/ManageArtifacts.md) - ## Changelog -**Change log** from previous v3.0.0.2 release: [View Here](CHANGELOG.md) - -## Reporting issues - -We encourage you to report any issues and documentation faults regarding Kubernetes and Helm resources -for WSO2 API Management. Please report your issues [here](https://github.com/wso2/kubernetes-apim/issues). - -## Contact us - -WSO2 developers can be contacted via the following mailing lists: - -* WSO2 Developers Mailing List : [dev@wso2.org](mailto:dev@wso2.org) -* WSO2 Architecture Mailing List : [architecture@wso2.org](mailto:architecture@wso2.org) +**Change log** from previous v3.0.0.3 release: [View Here](CHANGELOG.md) diff --git a/advanced/ManageArtifacts.md b/advanced/ManageArtifacts.md deleted file mode 100644 index 22a658f0..00000000 --- a/advanced/ManageArtifacts.md +++ /dev/null @@ -1,95 +0,0 @@ -# Manager Non-Configuration Files - -## How to introduce additional artifacts - -If you intend to pass on any additional artifacts such as, third-party libraries, OSGi bundles and security related artifacts to the Kubernetes cluster, -you may mount the desired content to `/home/wso2carbon/wso2-artifact-volume` directory path within a WSO2 product Docker container. - -The following example depicts how this can be achieved when passing additional artifacts to WSO2 API Manager nodes -in a clustered deployment of WSO2 API Manager: - -**[1] 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.** - -**[2] Create and export a directory within the NFS server instance.** - -**[3] Add the additional 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.** - -**[4] Grant ownership to `wso2carbon` user and `wso2` group, for the directory created in step [2].** - - ``` - sudo chown -R wso2carbon:wso2 - ``` - -**[5] Grant read-write-execute permissions to the `wso2carbon` user, for the directory created in step [2].** - - ``` - chmod -R 700 - ``` - -**[6] Map the directory created in step [2] to a Kubernetes [Persistent Volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) -in the persistent volume resource file `/pattern-1/volumes/persistent-volumes.yaml`** - -For example, append the following entry to the file: - -``` -apiVersion: v1 -kind: PersistentVolume -metadata: - name: apim-additional-artifact-pv - labels: - purpose: apim-additional-artifacts -spec: - capacity: - storage: 1Gi - accessModes: - - ReadWriteMany - persistentVolumeReclaimPolicy: Retain - nfs: - server: - path: "" -``` - -Provide the appropriate `NFS_SERVER_IP` and `NFS_LOCATION_PATH`. - -**[7] Create a Kubernetes Persistent Volume Claim to bind with the Kubernetes Persistent Volume defined in step [6].** - -For example, append the following entry to the file `/pattern-1/apim/wso2apim-volume-claim.yaml`: - -``` -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: apim-additional-artifact-volume-claim -spec: - accessModes: - - ReadWriteMany - resources: - requests: - storage: 1Gi - storageClassName: "" - selector: - matchLabels: - purpose: apim-additional-artifacts -``` - -**[8] 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 -`/pattern-1/apim/wso2apim-deployment.yaml` file as follows: - -``` -volumeMounts: -... -- name: apim-additional-artifact-storage-volume - mountPath: "/home/wso2carbon/wso2-artifact-volume" - -volumes: -... -- name: apim-additional-artifact-storage-volume - persistentVolumeClaim: - claimName: apim-additional-artifact-volume-claim -``` - -**[9] Deploy the Kubernetes resources as defined in section **Quick Start Guide** for pattern 1 of WSO2 API Manager.** diff --git a/advanced/ManageConfigurations.md b/advanced/ManageConfigurations.md deleted file mode 100644 index 9720efb1..00000000 --- a/advanced/ManageConfigurations.md +++ /dev/null @@ -1,86 +0,0 @@ -# Managing Configurations - -## 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 `/pattern-1/confs` -directory. The Kubernetes ConfigMaps are generated from these files. - -If you intend to pass on any additional configuration changes, you may use Kubernetes ConfigMaps. Follow the -steps below to achieve it. - -**[1] 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.** - -**[2] Create a Kubernetes ConfigMap from the file(s), which contains the relevant configuration changes.** - -The need to create a Kubernetes ConfigMap may depend on the type of file(s) to be passed on to the cluster, as follows: - -***[i] If the additional configuration is part of a file, which is among the minimum set of files with configuration changes required to setup -the particular product deployment pattern, use the same copy of the file to pass on the configuration.*** - -e.g. `/pattern-1/confs/apim/carbon.xml` is a file which is part of the minimum set of files with configuration changes required for -pattern 1 of WSO2 API Manager. If you intend to make the configuration change in the `/repository/conf/carbon.xml` -file in the product pack (which is the original file corresponding to `/pattern-1/confs/apim/carbon.xml` file), -make the configuration change within the file copy `/pattern-1/confs/apim/carbon.xml`. - -***[ii] If the additional configuration file is not included among the minimum set of files with configuration changes required to setup -a particular product deployment pattern, but is part of a directory within the original product pack to which you already pass other configuration files -using a Kubernetes ConfigMap, include the file within the appropriate location in `/pattern-1/confs` folder or any of its sub-folders.*** - -e.g. Assume that you need to change a configuration in `/repository/conf/datasources/metrics-datasources.xml` file. -`/repository/conf/datasources/metrics-datasources.xml` is not among the minimum set of configuration files adjusted -for pattern 1 of WSO2 API Manager. A Kubernetes ConfigMap is already created from `/pattern-1/confs/datasources` folder, -passing configuration files to `/repository/conf/datasources/` in the original product pack. Hence, you can add a copy of the `metrics-datasources.xml` -with relevant changes to `/pattern-1/confs/datasources` folder, in order to pass on the configuration file. - -***[iii] If the additional configuration file is not included among the minimum set of files with configuration changes required to setup a particular product -deployment pattern and is **not** part of any directory within the original product pack to which you already pass other configuration files -using Kubernetes ConfigMaps, follow the steps given below along with appropriate examples in each step.*** - -For example, assume that you need to pass on a copy of the changed `/repository/conf/tomcat/catalina-server.xml` file -to the Kubernetes cluster, for pattern 1 of WSO2 API Manager. `` is the path to a local copy of -`/repository/conf/tomcat/catalina-server.xml` file. - -* Create a folder in your local machine's filesystem, add the file with configuration changes to the created folder and -create a Kubernetes ConfigMap. - -e.g. - -``` -# create a folder -mkdir config - -# copy the changed configuration file to the created folder -cp config - -# create a Kubernetes ConfigMap -kubectl create configmap apim-conf-tomcat --from-file=config/ -``` - -* Populate a volume with data stored in the created Kubernetes ConfigMap. For this purpose, update the appropriate -Kubernetes [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) resource(s). When mounting -the created Kubernetes ConfigMap at the product container, it has to be mounted to the relevant path within the -`/home/wso2carbon/wso2-config-volume` folder in the product container, while maintaining the appropriate WSO2 product home folder structure. - -e.g. Update the volumes' (`spec.template.spec.volumes`) and volume mounts' (`spec.template.spec.containers[wso2apim-with-analytics-apim-worker].volumeMounts`) sections in -`/pattern-1/apim/wso2apim-deployment.yaml` file. The `mountPath` (which is `/home/wso2carbon/wso2-config-volume/repository/conf/tomcat`) -has been derived based on the target folder structure within the original product pack (which is `/repository/conf/tomcat`) and assuming that -`/home/wso2carbon/wso2-config-volume` is the product home root folder. - -``` -volumeMounts: -... -- name: apim-tomcat-config-volume - mountPath: "/home/wso2carbon/wso2-config-volume/repository/conf/tomcat" - -volumes: -... -- name: apim-tomcat-config-volume - configMap: - name: apim-conf-tomcat -``` - -**[3] Deploy the Kubernetes resources as defined in section **Quick Start Guide** for the relevant deployment pattern.** diff --git a/advanced/am-pattern-1/README.md b/advanced/am-pattern-1/README.md index f96c3f2c..535db01a 100644 --- a/advanced/am-pattern-1/README.md +++ b/advanced/am-pattern-1/README.md @@ -9,9 +9,15 @@ ## Prerequisites -* In order to use WSO2 Helm resources, you need an active [WSO2 Subscription](https://wso2.com/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). - Otherwise you can proceed with Docker images, which are created using GA releases.

+* About WSO2 product Docker images used for the Kubernetes deployment + + For a production grade deployment of the desired WSO2 product-version, it is highly recommended to use the relevant + Docker image which packages [WSO2 Updates](https://wso2.com/updates), available at [WSO2 Private Docker Registry](https://docker.wso2.com/). + In order to use WSO2 product Docker images with Updates, you need an active [WSO2 Subscription](https://wso2.com/subscription). + + Otherwise, you can proceed with WSO2 product Docker images available at [DockerHub](https://hub.docker.com/u/wso2/), which + package General Availability (GA) versions of WSO2 products with no WSO2 Updates. +

* Install * [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) diff --git a/advanced/am-pattern-2/README.md b/advanced/am-pattern-2/README.md index 4ee87669..20d97b3a 100644 --- a/advanced/am-pattern-2/README.md +++ b/advanced/am-pattern-2/README.md @@ -9,9 +9,15 @@ ## Prerequisites -* In order to use WSO2 Helm resources, you need an active [WSO2 Subscription](https://wso2.com/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). - Otherwise you can proceed with Docker images, which are created using GA releases.

+* About WSO2 product Docker images used for the Kubernetes deployment + + For a production grade deployment of the desired WSO2 product-version, it is highly recommended to use the relevant + Docker image which packages [WSO2 Updates](https://wso2.com/updates), available at [WSO2 Private Docker Registry](https://docker.wso2.com/). + In order to use WSO2 product Docker images with Updates, you need an active [WSO2 Subscription](https://wso2.com/subscription). + + Otherwise, you can proceed with WSO2 product Docker images available at [DockerHub](https://hub.docker.com/u/wso2/), which + package General Availability (GA) versions of WSO2 products with no WSO2 Updates. +

* 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/) in order to run the steps diff --git a/advanced/am-pattern-3/README.md b/advanced/am-pattern-3/README.md index 941e3ef5..44817439 100644 --- a/advanced/am-pattern-3/README.md +++ b/advanced/am-pattern-3/README.md @@ -9,9 +9,15 @@ ## Prerequisites -* In order to use WSO2 Helm resources, you need an active [WSO2 Subscription](https://wso2.com/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). - Otherwise you can proceed with Docker images, which are created using GA releases.

+* About WSO2 product Docker images used for the Kubernetes deployment + + For a production grade deployment of the desired WSO2 product-version, it is highly recommended to use the relevant + Docker image which packages [WSO2 Updates](https://wso2.com/updates), available at [WSO2 Private Docker Registry](https://docker.wso2.com/). + In order to use WSO2 product Docker images with Updates, you need an active [WSO2 Subscription](https://wso2.com/subscription). + + Otherwise, you can proceed with WSO2 product Docker images available at [DockerHub](https://hub.docker.com/u/wso2/), which + package General Availability (GA) versions of WSO2 products with no WSO2 Updates. +

* 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/) in order to run the steps