├── .gitignore ├── LICENSE ├── README.md ├── build └── Building.md ├── deploy ├── Deploying.md └── Managing_Keystores_And_Truststores.md ├── imgs ├── build │ ├── docker-adoption.png │ └── docker-usage.jpg ├── deploy │ └── kubernetes-adoption.png └── wso2.jpg ├── issue_template.md ├── pull_request_template.md ├── push └── Pushing.md ├── route └── Routing.md ├── scale └── Scaling_Deployments.md ├── store └── Persisting_And_Sharing.md └── update └── Propagating_Updates.md /.gitignore: -------------------------------------------------------------------------------- 1 | # Compiled class file 2 | *.class 3 | 4 | # Log file 5 | *.log 6 | 7 | # BlueJ files 8 | *.ctxt 9 | 10 | # Mobile Tools for Java (J2ME) 11 | .mtj.tmp/ 12 | 13 | # Package Files # 14 | *.jar 15 | *.war 16 | *.nar 17 | *.ear 18 | *.zip 19 | *.tar.gz 20 | *.rar 21 | 22 | # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml 23 | hs_err_pid* 24 | 25 | # IntelliJ IDEA metatdata 26 | .idea 27 | 28 | .DS_Store 29 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Running WSO2 Products on Containerization Platforms 4 | The Guide of Best Practices and Recommendations 5 | 6 | ## Table of Contents 7 | - ### [1. Building a container image](./build/Building.md) 8 | * [1.1. Why should you choose Docker as your container runtime ?](./build/Building.md#why-docker) 9 | * [1.2. Using WSO2 images](./build/Building.md#using-wso2-images) 10 | * [1.3. Building from source](./build/Building.md#building-from-source) 11 | * [1.4. Tips to harden your image](./build/Building.md#tips-to-harden-your-image) 12 | * [1.5. Tips on Tagging](./build/Building.md#tips-on-tagging) 13 | * [1.6. Vulnerability scanning and container security check](./build/Building.md#scanning) 14 | * [1.7. Image signing and Verification](./build/Building.md#signing) 15 | 16 | - ### [2. Pushing your image to a container registry](./push/Pushing.md) 17 | * [2.1. Why should you have your own private container registry ?](./push/Pushing.md#why-private-registry) 18 | * [2.2. How to secure your private container registry ?](./push/Pushing.md#how-to-secure) 19 | * [2.3. Scanning and Auditing](./push/Pushing.md#scanning-auditing) 20 | 21 | - ### [3. Deploying into production](./deploy/Deploying.md) 22 | * [3.1. Why do you need a container orchestrator ?](./deploy/Deploying.md) 23 | * [3.2. Why should you choose Kubernetes ?](./deploy/Deploying.md) 24 | * [3.3. Kubernetes Vs. OpenShift ?](./deploy/Deploying.md) 25 | * [3.4. Helm as package manager](./deploy/Deploying.md) 26 | * [3.5. Supporting Infrastructure](./deploy/Deploying.md) 27 | * [3.6. Resource Allocation](./deploy/Deploying.md) 28 | * [3.7. Deployment definition tips](./deploy/Deploying.md) 29 | * [3.8. Managing configurations](./deploy/Deploying.md) 30 | * [3.9. Managing keystores, certificates and other artifacts](./deploy/Managing_Keystores_And_Truststores.md) 31 | * [3.10. Managing databases](./deploy/Deploying.md) 32 | * [3.11. Production deployment tips](./deploy/Deploying.md) 33 | * [3.12. Managing security](./deploy/Deploying.md) 34 | 35 | - ### [4. Storage](./store/Persisting_And_Sharing.md) 36 | * [4.1. Why do we need storage for WSO2 products ?](./store/Persisting_And_Sharing.md#why-do-we-need-to-store?) 37 | * [4.2. Recommended storage options for WSO2 products](./store/Persisting_And_Sharing.md#recommended-storage-options-for-wso2-products) 38 | * [4.3. Storage binding tips](./store/Persisting_And_Sharing.md) 39 | * [4.4. Storage type and size](./store/Persisting_And_Sharing.md) 40 | 41 | - ### [5. Routing](./route/Routing.md) 42 | * [5.1. Exposing your application to outside](./route/Routing.md#exposing-your-application-to-outside) 43 | * [5.2. Configuring hostnames](./route/Routing.md#configuring-hostname) 44 | * [5.3. Configuring SSL](./route/Routing.md#configuring-ssl) 45 | * [5.4. DNS mapping](./route/Routing.md#dns-mapping) 46 | * [5.5. Tips on Session Affinity](./route/Routing.md#tips-on-session-affinity) 47 | 48 | - ### [6. Scaling your deployment](./scale/Scaling_Deployments.md) 49 | * [6.1. What is scaling ?](./scale/Scaling_Deployments.md#what-is-scaling?) 50 | * [6.2. When do we need to scale ?](./scale/Scaling_Deployments.md#when-do-we-need-to-scale?) 51 | * [6.3. Scaling metrics](./scale/Scaling_Deployments.md#scaling-metrics) 52 | * [6.4. Scaling WSO2 product profiles](./scale/Scaling_Deployments.md#scaling-wso2-product-profiles) 53 | * [6.5. Scaling strategies](./scale/Scaling_Deployments.md#scaling-strategies) 54 | 55 | - ### [7. Propagating Updates](./update/Propagating_Updates.md) 56 | * [7.1. When do we need to update ?](./update/Propagating_Updates.md#when-do-we-need-to-update?) 57 | * [7.2. Simplest way to perform an update](./update/Propagating_Updates.md#simplest-way-to-perform-an-update) 58 | * [7.3. Achieve zero downtime](./update/Propagating_Updates.md#achieve-zero-downtime) 59 | 60 | - ### [8. Publishing Logs](https://github.com/wso2/container-guide) 61 | * [8.1. Why do we need centralized logging ?](https://github.com/wso2/container-guide) 62 | * [8.2. Centralized logging with EFK](https://github.com/wso2/container-guide) 63 | * [8.3. Logging storage and Backup](https://github.com/wso2/container-guide) 64 | 65 | - ### [9. Monitoring and Alerting](https://github.com/wso2/container-guide) 66 | * [9.1. Why do we need metrics monitoring](https://github.com/wso2/container-guide) 67 | * [9.2. Metrics monitoring with Prometheus and Kibana](https://github.com/wso2/container-guide) 68 | * [9.3. Prometheus operator and exporters](https://github.com/wso2/container-guide) 69 | * [9.4. Alertmanager Integration with Prometheus](https://github.com/wso2/container-guide) 70 | * [9.5. Monitoring storage and Backup](https://github.com/wso2/container-guide) 71 | 72 | - ### [10. Development and Testing](https://github.com/wso2/container-guide) 73 | * [10.1. Planning your non-production environments](https://github.com/wso2/container-guide) 74 | * [10.2. Kubernetes Vs. Openshift way of execution](https://github.com/wso2/container-guide) 75 | 76 | - ### [11. Maintenance](https://github.com/wso2/container-guide) 77 | * [11.1. Importance of CI/CD](https://github.com/wso2/container-guide) 78 | * [11.2. WSO2 Kubernetes Pipeline](https://github.com/wso2/container-guide) 79 | 80 | - ### [12. A deployment checklist in summary](https://github.com/wso2/container-guide) 81 | * [12.1. Building a container image](https://github.com/wso2/container-guide) 82 | * [12.2. Pushing your image to a container registry](https://github.com/wso2/container-guide) 83 | * [12.3. Deploying into production](https://github.com/wso2/container-guide) 84 | * [12.4. Scaling your deployment](https://github.com/wso2/container-guide) 85 | * [12.5. Propagating updates](https://github.com/wso2/container-guide) 86 | * [12.6. Publishing and analysing logs](https://github.com/wso2/container-guide) 87 | * [12.7. Monitoring and Alerting](https://github.com/wso2/container-guide) 88 | * [12.8. Disaster Recovery](https://github.com/wso2/container-guide) 89 | * [12.9. Development and Testing](https://github.com/wso2/container-guide) 90 | * [12.10. Maintenance](https://github.com/wso2/container-guide) 91 | 92 | - ### [13. Appendix](https://github.com/wso2/container-guide) -------------------------------------------------------------------------------- /build/Building.md: -------------------------------------------------------------------------------- 1 | # 1. Building a container image 2 | 3 | This chapter depicts important information about building your first WSO2 container image. 4 | 5 | ### Contents 6 | 7 | The following will be discussed in detail in the document. 8 | 9 | * [1.1. Why should you choose Docker as your container runtime ?](#why-docker) 10 | * [1.2. Using WSO2 images](#using-wso2-images) 11 | * [1.3. Building from source](#building-from-source) 12 | * [1.4. Tips to harden your image](#tips-to-harden-your-image) 13 | * [1.5. Tips on Tagging](#tips-on-tagging) 14 | * [1.6. Vulnerability scanning and container security check](#scanning) 15 | * [1.7. Image signing and Verification](#signing) 16 | 17 |
18 | 19 | ## 1.1. Why should you choose Docker as your container runtime ? 20 | 21 | Started just 7 years ago in 2013, Docker introduced what would become the industry standard for containers and is undeniably yet the defacto standard to build, share and run containerized apps. 22 | 23 | 24 | 25 | Among many factors which led WSO2 to choose and recommend Docker as its first choice for a container runtime, following are key. 26 | 27 | * Docker’s ability to manage a complete container lifecycle. 28 | * Less learning curve and advanced feature set. 29 | * Wide community support towards its development and maintenance. 30 | * High popularity and customer demand. 31 | 32 |
33 | 34 | 35 | 36 | ## 1.2. Using WSO2 images 37 | 38 | WSO2-curated product Docker images are available for usage from both : 39 | 40 | [1] [Docker Hub](https://hub.docker.com/u/wso2/) :
41 | * Contains images built with the inclusion of GA released product packs and is publicly available for use free of charge. 42 | 43 | [2] [WSO2 Private Docker Registry, docker.wso2.com](https://docker.wso2.com/) :
44 | * Contains Docker images built with the inclusion of regularly updated product packs and is accessible only for its subscribed customers. 45 | 46 | WSO2 recommends using these images in containerized deployments of WSO2 products. This is mainly because WSO2 has aligned its Docker images with its recommended best practices for product deployments. 47 | 48 | Following are some of the key features of WSO2 product Docker images, which aligns them with WSO2-recommended best practices for container based product deployments: 49 | 50 | * *WSO2 recommends applying changes to the default configurations of a WSO2 product running inside a container via a volume mount. Our Docker images support this feature via a dedicated volume mount by the name:* ```wso2-config-volume```
(Refer to [this article](https://medium.com/faun/wso2-products-dockerized-advanced-usage-part-1-ae255ef02661) for more details) 51 | 52 | * *WSO2 recommends introducing additional artifacts / non-configuration files (e.g. third-party libraries, Carbon extensions in the form
of OSGi bundles, Carbon Applications or any security-related artifacts such as Java Keystore files) to a WSO2 product
running inside a container via a volume mount. Our Docker images support this feature via a dedicated volume
mount by the name:* ```wso2-artifact-volume``` (Refer to [this article](https://medium.com/faun/wso2-products-dockerized-advanced-usage-part-2-9c851b0db557) for more details) 53 | 54 | * *WSO2 recommends introducing patches (or hotfixes) to a WSO2 product running inside a container via a volume mount.
Our Docker images support this feature via a dedicated volume mount by the name:* ```wso2-patch-volume```
(Refer to [this article](https://medium.com/faun/wso2-products-dockerized-advanced-usage-part-2-9c851b0db557) for more details) 55 | 56 | * *Supports passing WSO2 product startup options.* 57 | (Refer to [this article](https://medium.com/faun/wso2-products-dockerized-remote-debug-dockerized-wso2-products-with-intellij-idea-111ca8ae60c) as an example for more details) 58 | 59 | WSO2 has followed an array of [best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) and [guidelines](https://github.com/docker-library/official-images#review-guidelines) recommended by the Docker community during the implementation of its product Docker resources. 60 | 61 | Some of the best practices and guidelines that are followed for Dockerfiles and entry point scripts are explained below. 62 | 63 | * *Minimized container image size:* 64 | 65 | + *Minimizing the number instructions in the Dockerfile that would create sizeable image layers, leading to reduced image size.*
(Refer to [this section](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#minimize-the-number-of-layers) for advanced details) 66 | 67 | + *The product distribution pack and its dependencies are removed to prevent the Docker image size from increasing.
Only the necessary software packages have been installed.* (Refer to [this section](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#dont-install-unnecessary-packages) for more details) 68 | 69 | * *Non-root user:* 70 | 71 | + *WSO2-released Docker images ship with ‘wso2carbon’ non-root user for running WSO2 products.* 72 | 73 | * *Heightened Clarity:* 74 | 75 | + *Due to sorted multi-line arguments.* (Refer to [this section](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#sort-multi-line-arguments) for more details) 76 | 77 | In case of an extension, WSO2 recommends using an official WSO2 product Docker image as the base of that extended Docker image. 78 | 79 |
80 | 81 | ## 1.3. Building from source 82 | 83 | In case if the preference is to build the images from source, since this gives you greater control over the image and the conditions
affecting its security, WSO2 recommends referring to the official GitHub release of the Docker resources of the relevant
WSO2 product to write your Dockerfile and build a WSO2 product Docker image by source. 84 | 85 | Also in case if your preferred JDK is different from the default that we pack, you can follow this approach to build your own Docker image. 86 | 87 | Useful reference points: 88 | 89 | [1] [Docker resources for WSO2 API Management](https://github.com/wso2/docker-apim)
90 | [2] [Docker resources for WSO2 Integration](https://github.com/wso2/docker-ei)
91 | [3] [Docker resources for WSO2 Identity and Access Management](https://github.com/wso2/docker-is)
92 | [4] [Docker resources for WSO2 Open Banking](https://github.com/wso2/docker-open-banking) 93 | 94 |
95 | 96 | ## 1.4. Tips to harden your image 97 | 98 | Key takeaways from our experience to write your Dockerfile : 99 | 100 | ``` 101 | [1] Verify Authenticity of any software installed in the image 102 | [2] Always use HTTPS for files added remotely 103 | [3] From directive: Use specific / unique tag 104 | [4] Never run as root 105 | [5] USER directive: Always 106 | [6] Drop privileges where necessary 107 | [7] Expose only required ports 108 | ``` 109 | 110 | Useful reference points: 111 | 112 | [1] [Docker resources for WSO2 API Management](https://github.com/wso2/docker-apim)
113 | [2] [Docker resources for WSO2 Integration](https://github.com/wso2/docker-ei)
114 | [3] [Docker resources for WSO2 Identity and Access Management](https://github.com/wso2/docker-is)
115 | [4] [Docker resources for WSO2 Open Banking](https://github.com/wso2/docker-open-banking) 116 | 117 |
118 | 119 | ## 1.5. Tips on Tagging 120 | 121 | WSO2 product docker image tagging strategy is simple. 122 | 123 | [1] Per each product version, we maintain an image queue.
124 | This queue can hold a maximum of 3 images from the oldest to the latest and each bear a unique tag to distinguish itself from the other. 125 | 126 | * *E.g.* 127 |
128 | *wso2am:3.1.0.1591023165861.2 - Oldest*
129 | *wso2am:3.1.0.1591230650206.3 - 2nd oldest*
130 | *wso2am:3.1.0.1592240780334.4 - latest*
131 | 132 | Unique tag: :.. 133 | 134 | This queue is regularly updated with a new image having an update (or in other words, a patch) either to the product or Docker artifacts. When a new image is pushed, the oldest of the 3 is removed from the registry on a first-in-first-out (FIFO) basis. 135 | 136 | Unique tags are ideal in referring to an image during deployments and we recommend customers to use this tag when they directly use WSO2 images for their deployments without any customizations. 137 | 138 | [2] We also maintain one stable tag per each product version.
139 | A stable tag is always pointed to the latest Docker image of a particular product version. 140 | 141 | Taking the same example from [1], 142 | 143 | * *E.g.* 144 |
145 | *wso2am:3.1.0.1591023165861.2 - Oldest*
146 | *wso2am:3.1.0.1591230650206.3 - 2nd oldest*
147 | *wso2am:3.1.0.1592240780334.4 (unique), wso2am:3.1.0 (Stable) - latest*
148 | 149 | Stable tag: : 150 | 151 | Stable tags are ideal in referring to a base image during Docker build. We recommend customers to use this tag when they want to build their custom images on top of the product Docker images that we host. 152 | 153 | [3] We maintain a latest tag per each product.
154 | The latest tag is also a stable tag and is always pointed to the latest Docker image of a product repo. 155 | 156 | Taking the same example from [2], if `3.1.0` is the latest version of wso2am, 157 | 158 | * *E.g.* 159 |
160 | *wso2am:3.1.0.1591023165861.2 - Oldest*
161 | *wso2am:3.1.0.1591230650206.3 - 2nd oldest*
162 | *wso2am:3.1.0.1592240780334.4 (unique), wso2am:3.1.0 (Stable), wso2am:latest (stable) - latest* 163 | 164 | Latest tag: :latest 165 | 166 | WSO2 recommends a similar tagging mechanism to its customers. 167 | 168 | Key takeaways: 169 | 170 | [1] Uniquely identifying an image is key.
171 | [2] Use unique tags for images used directly in your deployments.
172 | [3] A stable tag is recommended only for an image used as a base for your deployed image. 173 | 174 |
175 | 176 | ## 1.6. Vulnerability scanning and container security check 177 | 178 | If a container image includes a vulnerability, then every container generated using the image will also include that vulnerability. Hence it is really important that you scan the newly built image for any vulnerabilities prior to the promotion of the image into a registry. 179 | 180 | Among many other alternative scanning tools, WSO2 uses and would also like to recommend both [Trivy](https://github.com/aquasecurity/trivy) and [Clair](https://coreos.com/clair/docs/latest) for this purpose. 181 | 182 | `Trivy` : is a simple and comprehensive vulnerability scanner for containers and other artifacts. Trivy detects vulnerabilities of OS packages (Alpine, RHEL, CentOS, etc.) and application dependencies (Bundler, Composer, npm, yarn, etc.). 183 | 184 | `Clair` : is an open source project for the static analysis of vulnerabilities in Docker containers. Clair scans each container layer and provides a notification of vulnerabilities that may be a threat, based on the Common Vulnerabilities and Exposures database (CVE) and similar databases from Red Hat, Ubuntu, and Debian. 185 | 186 | Additionally, the Center for Internet Security (CIS) has a [Docker Benchmark](https://www.cisecurity.org/benchmark/docker) for evaluating the security of a Docker container. 187 | 188 | Docker provides an open source script called [Docker Bench for Security](https://github.com/docker/docker-bench-security). You can use this script to validate a running Docker container against the CIS Docker Benchmark. It can help you verify many items in the CIS Docker Benchmark, but not all items are verifiable with the script. For example, the script cannot verify if the host for the container is hardened or if the container image includes personal data. Review all items in the benchmark and identify those that might need additional verification. 189 | 190 |
191 | 192 | ## 1.7. Image signing and Verification 193 | 194 | Whether you are using a private image registry in-house or a public registry such as Docker Hub, it's important to know that you are running only the code that you actually intend to run. The potential for malicious code or man-in-the-middle attacks on downloads is an important factor in protecting your container images. 195 | 196 | As such, Docker supports the ability to sign images and verify that the contents have not changed. Publishers can use keys to sign the images when they are pushed to the registries and users can verify the signature on the client-side when downloading them for use. 197 | -------------------------------------------------------------------------------- /deploy/Deploying.md: -------------------------------------------------------------------------------- 1 | # 3. Deploying into production 2 | 3 | This chapter depicts important information about deploying your images into production. 4 | 5 | ### Contents 6 | 7 | The following will be discussed in detail in the document. 8 | 9 | * [3.1. Why do you need a container orchestrator ?](#why-orchestrator) 10 | * [3.2. Why should you choose Kubernetes ?](#why-kubernetes) 11 | * [3.3. Kubernetes Vs. OpenShift ?](#kubernetes-openshift) 12 | 13 |
14 | 15 | ## 3.1. Why do you need a container orchestrator ? 16 | 17 | Even though it is easy to manage, maintain, and run all your containers in a single node cluster this practice would lead to a single point of failure (if the node suddenly malfunctions due to some problems). As a result, it’s always advisable to divide your containers into two or more nodes in a cluster. However, depending on the load we not only have to increase the number of containers we manage, but we will also have to increase the number of nodes we manage for the cluster. Conversely, the higher the number of containers and nodes, the effort and complexity of managing the cluster increase in high proportions. Doing this manually is a daunting task and is highly error prone. 18 | 19 | This is where a container orchestration platform comes handy as a solution to the problem. It can manage all the bare metal machines and virtual machines on which you need to run your containers. Furthermore, it could also manage your containers by launching them on the underlying machines, making sure they are distributed, and keeping them healthy. 20 | 21 |
22 | 23 | ## 3.2. Why should you choose Kubernetes ? 24 | 25 | When it comes to the three leading container orchestration platforms, i.e., Mesos, Kubernetes, and Docker Swarm, Kubernetes is the undisputed leader due to the following reasons: 26 | 27 | * Wide adoption 28 | * Proven, battle-tested solution 29 | * Open source 30 | * High Availability 31 | * Scalability 32 | * Portability 33 | * Powerful and easy-to-use features 34 | 35 |
36 | 37 | 38 | 39 |
40 | 41 | With its wide adoption and powerful, easy-to-use features, we at WSO2 believe that it can soon become the defacto container orchestration platform standard in the world. It is for this reason that we continue to provide development support for Kubernetes-based container deployments of our products (as we have done for more than two years). 42 | -------------------------------------------------------------------------------- /deploy/Managing_Keystores_And_Truststores.md: -------------------------------------------------------------------------------- 1 | # Managing Java Keystores and Truststores 2 | 3 | This chapter depicts important information about managing Java keystores and truststores in a container based 4 | WSO2 product deployment. 5 | 6 | ## Contents 7 | 8 | The following will be discussed in detail in the document. 9 | 10 | * [Asymmetric Encryption in WSO2 products](#asymmetric-encryption-in-wso2-products) 11 | * [Manage Keystores and Certificate Truststores in Container Based Deployments](#manage-keystores-and-certificate-truststores-in-container-based-deployments) 12 | 13 | ### Asymmetric Encryption in WSO2 Products 14 | 15 | WSO2 products use asymmetric encryption by default to ensure trust and secure tranfer of data. For advanced details, 16 | refer the official WSO2 [documentation](https://docs.wso2.com/display/ADMIN44x/Using+Asymmetric+Encryption#UsingAsymmetricEncryption-setting_up_keystoresUsageofkeystoresinWSO2products). 17 | 18 | [Java keystores and truststores](https://docs.wso2.com/display/ADMIN44x/Using+Asymmetric+Encryption#UsingAsymmetricEncryption-Understandingkeystoresandtruststores) 19 | are used to store SSL certificates required for asymmetric encryption. 20 | 21 | Refer to the official WSO2 [recommendations](https://docs.wso2.com/display/ADMIN44x/Using+Asymmetric+Encryption#UsingAsymmetricEncryption-recommendationsRecommendationsforsettingupkeystoresinWSO2products) 22 | for managing keystores prior to following this guide. 23 | 24 | ### Manage Keystores and Truststores in Container Based Deployments 25 | 26 | As per aforementioned WSO2 [recommendations](https://docs.wso2.com/display/ADMIN44x/Using+Asymmetric+Encryption#UsingAsymmetricEncryption-recommendationsRecommendationsforsettingupkeystoresinWSO2products), 27 | it is often required to customize the default, WSO2 product keystore and truststore in a production grade deployment. 28 | 29 | The most recommended approach for introducing a custom keystore or a truststore to a container based deployment is by using 30 | volume mounting to replace the default one with the custom one. 31 | 32 | 1. Prepare the custom Java keystore or truststore. 33 | 34 | Follow the official guidelines for [creating a new keystore](https://docs.wso2.com/display/ADMIN44x/Creating+New+Keystores#CreatingNewKeystores-Creatinganewkeystore) 35 | or [adding a Certificate Authority signed certificate to an existing keystore](https://docs.wso2.com/display/ADMIN44x/Creating+New+Keystores#CreatingNewKeystores-ca_certificateAddingCA-signedcertificatestokeystores) 36 | as per your preference. 37 | 38 | To import certificates to a truststore, follow the official [documentation](https://docs.wso2.com/display/ADMIN44x/Creating+New+Keystores#CreatingNewKeystores-Step3:Importingcertificatestothetruststore). 39 | 40 | 2. Add the keystore to the product container via a volume mount depending on the container platform. 41 | 42 | We recommend you to use the volume mount allocated for non-configuration resources in WSO2 product containers 43 | (i.e. `/home/wso2carbon/wso2-artifact-volume`) for this purpose. 44 | 45 | In Carbon Kernel **version 4** based products, the default `wso2carbon.jks` keystore is located at the 46 | `/repository/resources/security` directory. Thus, you may mount the volume containing the 47 | custom keystore to `/home/wso2carbon/wso2-artifact-volume/repository/resources/security` directory. 48 | 49 | In Carbon Kernel **version 5** based products, the default `wso2carbon.jks` keystore is located at the 50 | `/resources/security` directory. Thus, you may mount the volume containing the custom keystore 51 | to `/home/wso2carbon/wso2-artifact-volume/resources/security` directory. 52 | 53 | 3. Add the truststore to the product container via a volume mount depending on the container platform. 54 | 55 | We recommend you to use the volume mount allocated for non-configuration resources in WSO2 product containers 56 | (i.e. `/home/wso2carbon/wso2-artifact-volume`) for this purpose. 57 | 58 | In Carbon Kernel **version 4** based products, the default `client-truststore.jks` truststore is located at the 59 | `/repository/resources/security` directory. Thus, you may mount the volume containing the 60 | custom keystore to `/home/wso2carbon/wso2-artifact-volume/repository/resources/security` directory. 61 | 62 | In Carbon Kernel **version 5** based products, the default `client-truststore.jks` truststore is located at the 63 | `/resources/security` directory. Thus, you may mount the volume containing the custom keystore 64 | to `/home/wso2carbon/wso2-artifact-volume/resources/security` directory. 65 | 66 | > In Kubernetes based WSO2 product deployments, it is advisable that you use a ConfigMap resource to mount the custom keystore 67 | > and truststore. 68 | > 69 | > **Note:** Support for including binary data in Kubernetes ConfigMaps was introduced in version [`1.10`](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.10.md#apps). 70 | > 71 | > For further understanding peruse: 72 | > 73 | > 1. [Create a ConfigMap resource from the keystore file](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#create-configmaps-from-files) 74 | > 75 | > 2. [Add the ConfigMap data to a volume](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#add-configmap-data-to-a-volume) 76 | -------------------------------------------------------------------------------- /imgs/build/docker-adoption.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/wso2/container-guide/63116c0e2df872ab899876802eb143cdc9df6c97/imgs/build/docker-adoption.png -------------------------------------------------------------------------------- /imgs/build/docker-usage.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/wso2/container-guide/63116c0e2df872ab899876802eb143cdc9df6c97/imgs/build/docker-usage.jpg -------------------------------------------------------------------------------- /imgs/deploy/kubernetes-adoption.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/wso2/container-guide/63116c0e2df872ab899876802eb143cdc9df6c97/imgs/deploy/kubernetes-adoption.png -------------------------------------------------------------------------------- /imgs/wso2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/wso2/container-guide/63116c0e2df872ab899876802eb143cdc9df6c97/imgs/wso2.jpg -------------------------------------------------------------------------------- /issue_template.md: -------------------------------------------------------------------------------- 1 | **Description:** 2 | 3 | 4 | **Suggested Labels:** 5 | 6 | 7 | **Suggested Assignees:** 8 | 9 | 10 | **Affected Product Version:** 11 | 12 | **OS, DB, other environment details and versions:** 13 | 14 | **Steps to reproduce:** 15 | 16 | 17 | **Related Issues:** 18 | -------------------------------------------------------------------------------- /pull_request_template.md: -------------------------------------------------------------------------------- 1 | ## Purpose 2 | > Describe the problems, issues, or needs driving this feature/fix and include links to related issues in the following format: Resolves issue1, issue2, etc. 3 | 4 | ## Goals 5 | > Describe the solutions that this feature/fix will introduce to resolve the problems described above 6 | 7 | ## Approach 8 | > Describe how you are implementing the solutions. Include an animated GIF or screenshot if the change affects the UI (email documentation@wso2.com to review all UI text). Include a link to a Markdown file or Google doc if the feature write-up is too long to paste here. 9 | 10 | ## User stories 11 | > Summary of user stories addressed by this change> 12 | 13 | ## Release note 14 | > Brief description of the new feature or bug fix as it will appear in the release notes 15 | 16 | ## Documentation 17 | > Link(s) to product documentation that addresses the changes of this PR. If no doc impact, enter “N/A” plus brief explanation of why there’s no doc impact 18 | 19 | ## Training 20 | > Link to the PR for changes to the training content in https://github.com/wso2/WSO2-Training, if applicable 21 | 22 | ## Certification 23 | > Type “Sent” when you have provided new/updated certification questions, plus four answers for each question (correct answer highlighted in bold), based on this change. Certification questions/answers should be sent to certification@wso2.com and NOT pasted in this PR. If there is no impact on certification exams, type “N/A” and explain why. 24 | 25 | ## Marketing 26 | > Link to drafts of marketing content that will describe and promote this feature, including product page changes, technical articles, blog posts, videos, etc., if applicable 27 | 28 | ## Automation tests 29 | - Unit tests 30 | > Code coverage information 31 | - Integration tests 32 | > Details about the test cases and coverage 33 | 34 | ## Security checks 35 | - Followed secure coding standards in http://wso2.com/technical-reports/wso2-secure-engineering-guidelines? yes/no 36 | - Ran FindSecurityBugs plugin and verified report? yes/no 37 | - Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets? yes/no 38 | 39 | ## Samples 40 | > Provide high-level details about the samples related to this feature 41 | 42 | ## Related PRs 43 | > List any other related PRs 44 | 45 | ## Migrations (if applicable) 46 | > Describe migration steps and platforms on which migration has been tested 47 | 48 | ## Test environment 49 | > List all JDK versions, operating systems, databases, and browser/versions on which this feature/fix was tested 50 | 51 | ## Learning 52 | > Describe the research phase and any blog posts, patterns, libraries, or add-ons you used to solve the problem. -------------------------------------------------------------------------------- /push/Pushing.md: -------------------------------------------------------------------------------- 1 | # 2. Pushing your image to a container registry 2 | 3 | This chapter describes why it is important to push your image to a container registry. 4 | 5 | ### Contents 6 | 7 | The following will be discussed in detail in the document. 8 | 9 | * [2.1. Why should you have your own private container registry ?](#why-private-registry) 10 | * [2.2. How to secure your private container registry ?](#how-to-secure) 11 | * [2.3. Scanning and Auditing](#scanning-auditing) 12 | 13 |
14 | 15 | ## 2.1. Why should you have your own private container registry ? 16 | 17 | It is salient to own your private container registry because of the following reasons: 18 | 19 | [1] A private container registry with scanning capabilities and role-based access control offers leverage on security, governance, and management efficiency. 20 | 21 | [2] You do not have much control over the images stored in an external registry. New images could be added and already existing images could be removed from the registry at any time. For example, most registries of framework providers do not preserve all images they publish for a long time. 22 | 23 | This is also applicable to product Docker images available at [WSO2 Private Docker Registry](https://docker.wso2.com) mainly due to limitations of storage. For each product version, new images are being frequently added with the latest [WSO2 Updates](https://wso2.com/updates) to products and changes to docker resources used. With limitations of storage, not all images being pushed could be retained in the registry for a long time. 24 | 25 | As a result, WSO2 best advise the use of your own private container registry to host all the required images in your deployments, so that you have full control over them. In a rollback event, the recovery of previous version images is effortless with zero risks and dependence on outside sources. 26 | 27 | ## 2.2. How to secure your private container registry ? 28 | 29 | Your private Container registry is the place where you host all the images required for your deployment. When you push an image to the registry, it is always important to be sure that you push the exact image that you want to store in your registry. On the contrary, when an image is pulled from the registry, it is also vital to be sure that you pull the correct image that you want to retrieve from your registry. Since the transfer of data in both of these situations happens in HTTP, securing the transfer using `SSL security` is essential to avoid any man-in-the-middle attacks. 30 | 31 | Further to provide access only to authorized personnel even within your organization, it is also important that you enable at least `basic authentication` to secure your registry. 32 | 33 | ## 2.3. Scanning and Auditing 34 | 35 | If an image includes a vulnerability, then every container generated using that particular image will also include that vulnerability. New images and newer versions of existing images may be pushed frequently into your private registry. Every change carries with it the possibility of introducing a new vulnerability - and all too often, an old vulnerability resulting from the use of an outdated software package. 36 | 37 | `Scanning` : You need to schedule regular scans of your repository in order to detect such vulnerabilities. Most of the organizations that maintain major public registries provide their own scanning services (such as [Docker](https://docs.docker.com/docker-hub/official_images/#official-image-vulnerability-scanning) for their official images). Even for private registries, there are a plenty of security providers to offer extended scanning capabilities, with key features such as scanning-results alerts, and automatically preventing images that are not trusted from being used. 38 | 39 | `Auditing` : You can (and should) go beyond scanning for vulnerabilities by auditing images for age, as well as outdated packages. You can flag older images and those with older dependencies as outdated and schedule them for updating. Adopting a policy of regularly updating and refreshing older images makes it easy to eliminate vulnerabilities that may have gone undetected. -------------------------------------------------------------------------------- /route/Routing.md: -------------------------------------------------------------------------------- 1 | # Routing 2 | 3 | This document depicts important information about configuring routing for an existing WSO2 product deployment in a 4 | container platform. 5 | 6 | The following will be discussed in detail in the document. 7 | 8 | * [Exposing your application to outside](#exposing-your-application-to-outside) 9 | * [Configuring hostname](#configuring-hostname) 10 | * [DNS mapping](#dns-mapping) 11 | * [Configuring SSL](#configuring-ssl) 12 | * [Tips on Session Affinity](#tips-on-session-affinity) 13 | 14 | ### Exposing your application to outside 15 | 16 | We recommend the use of [official WSO2 product Helm Charts](https://hub.helm.sh/charts/wso2) for production grade WSO2 17 | product deployments in Kubernetes environments. [Kubernetes Ingress resources](https://kubernetes.io/docs/concepts/services-networking/ingress/) 18 | are used to expose WSO2 product services to outside of the Kubernetes environment. 19 | 20 | Kubernetes Ingress Controller is capable of performing the identification of the backend based on the hostname and 21 | path hostname and path of a given request. It also operates on the application layer of the network stack (HTTP) and 22 | can provide features like cookie-based session affinity and SSL terminations. 23 | 24 | >WSO2 recommend [Community NGINX](https://kubernetes.github.io/ingress-nginx/) as the Ingress controller for production 25 | >grade product deployments in Kubernetes environments. 26 | 27 | ### Configuring hostname 28 | 29 | For all the relevant WSO2 product profile services which need exposing to outside of the Kubernetes cluster must be 30 | exposed to outside with appropriate hostnames. 31 | >In official WSO2 product Helm charts, hostnames can be configured via user input (via values.yaml) as per user preference. 32 | 33 | ### DNS mapping 34 | 35 | In order to access the services that are exposed through the Ingress controller, it is required to add DNS record 36 | mappings where each configured host name should be resolved to the load balancer IP(EXTERNAL_IP) that fronts the Ingress 37 | controller. 38 | 39 | If the defined hostnames are not backed by a DNS service, for the purpose of evaluation you may add an entry mapping the 40 | hostnames and the external IP in the client-side Operating system(e.g., Ubuntu: `/etc/hosts`) as shown below. 41 | 42 | > \ 43 | 44 | ### Configuring SSL 45 | 46 | It is recommended to do SSL termination at load balancer in this case at Ingress controller. With this method, it is 47 | possible to manage production certificates for the entire Kubernetes cluster in a single location, the Ingress 48 | controller. 49 | 50 | With in the Kubernetes environment, WSO2 products use HTTPS with self-signed certificates for communication. 51 | 52 | There are two ways of configuring SSL termination for Ingress controller. 53 | 54 | 1. Use a wild card certificate as the default certificate 55 | * In this approach, all the services that are exposed should be configured with a host name within the wild card 56 | domain 57 | 2. Configure individual certificates for each host name 58 | * In this approach, it is possible to have different host name for each exposed service where each Ingress is 59 | configured with a certificate for a particular host name 60 | 61 | ### Tips on Session Affinity 62 | 63 | Some of the WSO2 products require to maintain the session of end user across subsequent HTTP calls. In a Kubernetes 64 | environment, **Session Affinity** must be configured at Ingress resources. 65 | 66 | > In **NGINX** ingress controller, **Cookie** based session affinity is used as the default. 67 | -------------------------------------------------------------------------------- /scale/Scaling_Deployments.md: -------------------------------------------------------------------------------- 1 | # Scaling Deployments 2 | 3 | This chapter depicts important information about scaling an existing WSO2 product deployment in a container platform. 4 | 5 | ## Contents 6 | 7 | The following will be discussed in detail in the document. 8 | 9 | * [What is scaling?](#what-is-scaling?) 10 | * [When do we need to scale?](#when-do-we-need-to-scale?) 11 | * [Scaling metrics](#scaling-metrics) 12 | * [Scaling WSO2 product profiles](#scaling-wso2-product-profiles) 13 | * [Scaling strategies](#scaling-strategies) 14 | 15 | ### What is scaling? 16 | 17 | In the context of a WSO2 product deployment, assuming that you have provided sufficient computing resources, 18 | scaling refers to increasing/decreasing the number of replicas of a given product profile. 19 | 20 | ### When do we need to scale? 21 | 22 | Following events may instigate scaling of an existing WSO2 product profile. 23 | 24 | * The current throughput per second (TPS) handled by the system surpasses a defined threshold TPS that can be handled 25 | via the available instances. 26 | 27 | * The current throughput per second (TPS) handled by the system decreases below a defined threshold TPS that can be handled 28 | via the available instances. 29 | 30 | ### Scaling metrics 31 | 32 | Thus, TPS handled by an instance of a particular product profile can be considered the primary metric considered for scaling. 33 | 34 | Also, secondary metrics such as CPU usage and memory usage of a given product profile instance can be considered. 35 | 36 | ### Scaling strategies 37 | 38 | * Scaling based on CPU 39 | 40 | WSO2 recommends auto scaling of profile instances to be configured with the average CPU threshold between 80%-90%. 41 | 42 | * Scaling based on memory 43 | 44 | WSO2 recommends auto scaling of profile instances to be configured with the average memory threshold between 80%-90%. 45 | 46 | ### Scaling WSO2 product profiles 47 | 48 | It has to be noted that scalability differ based on the WSO2 product profile. The following highlight such noteworthy cases. 49 | 50 | * Scaling API Manager product profiles 51 | 52 | Please refer to scaling recommendations for WSO2 API Manager product profiles defined 53 | [here](https://apim.docs.wso2.com/en/latest/learn/api-gateway/scaling-the-gateway/). 54 | 55 | * Stream Processor based deployments 56 | 57 | A minimum high availability deployment of Stream Processor based deployment is not scalable more than 2 replicas. 58 | Please see official [documentation](https://docs.wso2.com/display/SP440/Minimum+High+Availability+Deployment) 59 | for advanced details about this. 60 | -------------------------------------------------------------------------------- /store/Persisting_And_Sharing.md: -------------------------------------------------------------------------------- 1 | # 4. Persisting and Sharing 2 | 3 | This chapter depicts important information about runtime artifact storage of an existing WSO2 product deployment in a container platform. 4 | 5 | ## Contents 6 | 7 | The following will be discussed in detail in the document. 8 | 9 | * [4.1. Why do we need to store?](#why-do-we-need-to-store?) 10 | * [4.2. Recommended storage options for WSO2 products](#recommended-storage-options-for-wso2-products) 11 | 12 | ### Why do we need to store? 13 | 14 | In the context of WSO2 product deployment, the need for storage of artifacts arises due to the following reasons: 15 | 16 | * Persist created runtime artifacts 17 | 18 | * Share created runtime artifacts across multiple instances in deployments with high availability support 19 | 20 | > For example, in WSO2 API Manager production deployment patterns, it is recommended to use a suitable storage option 21 | for the aforementioned purposes. 22 | > 23 | > Following are some such scenarios. 24 | > 25 | > - Persist Apache Solr-based indexed data in every Publisher and DevPortal profile instance, individually 26 | > 27 | > - Persist and share API runtime artifacts (created in `/repository/deployment/server/synapse-configs`) directory 28 | > across multiple instances of the API Manager Gateway profile 29 | > 30 | > For advanced details on persistent runtime artifacts of WSO2 API Manager, please refer to the official 31 | [documentation](https://apim.docs.wso2.com/en/latest/install-and-setup/setup/reference/common-runtime-and-configuration-artifacts/#persistent-runtime-artifacts). 32 | 33 | ### Recommended storage options for WSO2 products 34 | 35 | As highlighted in the [previous](#why-do-we-need-to-store?) section, there are numerous use cases which instigate the need 36 | for storage in WSO2 product deployments. 37 | 38 | WSO2 recommends using the most suitable persistent storage solution depending on the scenario. 39 | 40 | * Persist runtime artifacts of a single instance: 41 | 42 | For this purpose, you may use any persistent storage solution supporting either `ReadWriteOnce` or `ReadWriteMany` 43 | [access modes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes). 44 | 45 | * Persist and share runtime artifacts across multiple instances of a product profile 46 | 47 | For this purpose, you may use any persistent storage solution supporting `ReadWriteMany` 48 | [access mode](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes). 49 | 50 | The following is a list of storage options using with production grade WSO2 product deployments in Kubernetes environments that 51 | have been tested along with the corresponding [Kubernetes StorageClasses](https://kubernetes.io/docs/concepts/storage/storage-classes/). 52 | 53 | * Network File System (NFS) 54 | 55 | - WSO2 product Helm charts use the stable [NFS Server Provisioner](https://hub.helm.sh/charts/stable/nfs-server-provisioner) 56 | to render a NFS server, for the purpose of evaluation. 57 | 58 | - WSO2 product deployments have been tried and tested with NFS based solutions like [Google FileStore](https://cloud.google.com/filestore) 59 | (please refer to instructions for [WSO2 API Manager](https://github.com/wso2/kubernetes-apim/issues/359#issuecomment-639729986) and 60 | [WSO2 Identity Server](https://github.com/wso2/kubernetes-is/issues/227#issuecomment-639735208)). 61 | 62 | * Ceph File System (CephFS) 63 | 64 | - WSO2 product deployments have been tested with [CephFS cluster deployed using the Rook Operator version `1.3`](https://rook.io/docs/rook/v1.3/ceph-quickstart.html). 65 | (Refer to instructions for [WSO2 API Manager](https://github.com/wso2/kubernetes-apim/issues/410#issuecomment-654070688) and 66 | [WSO2 Identity Server](https://github.com/wso2/kubernetes-is/issues/240#issuecomment-654681300)). 67 | 68 | * Azure Storage 69 | 70 | - WSO2 product deployments have been tested with [Azure File](https://azure.microsoft.com/en-us/services/storage/files/) 71 | storage solution (Refer to instructions for [WSO2 Open Banking](https://github.com/wso2/kubernetes-open-banking/issues/57#issuecomment-698404086)). 72 | -------------------------------------------------------------------------------- /update/Propagating_Updates.md: -------------------------------------------------------------------------------- 1 | # Propagating Updates 2 | 3 | This chapter depicts important information about updating an existing WSO2 product deployment in a container platform. 4 | 5 | ## Contents 6 | 7 | The following will be discussed in detail in the document. 8 | 9 | * [When do we need to update?](#when-do-we-need-to-update?) 10 | * [Simplest way to perform an update](#simplest-way-to-perform-an-update) 11 | * [Achieve zero downtime](#achieve-zero-downtime) 12 | 13 | ### When do we need to update? 14 | 15 | The following are some of the scenarios which instigates the need for an update to an existing 16 | WSO2 product deployment in a container platform. 17 | 18 | * Be abreast with product bug fixes and improvements by integrating [WSO2 Updates](https://wso2.com/updates) 19 | 20 | * Updates to configuration files 21 | 22 | * Updates to non-configuration resources 23 | 24 | For example, 25 | * Binaries such as, third-party libraries, Carbon extensions in the form of OSGi bundles, [Carbon Applications](https://docs.wso2.com/display/Carbon440/Working+with+Carbon+Applications) 26 | * Any security related artifacts such as, Java Keystore files 27 | 28 | * Changes to installation resources 29 | 30 | For example, 31 | * Container image source 32 | * Kubernetes/Helm resources 33 | 34 | ### Simplest way to perform an update 35 | 36 | We recommend the use of [official WSO2 product Helm Charts](https://hub.helm.sh/charts/wso2) for production grade WSO2 product deployments 37 | in Kubernetes environments. 38 | 39 | Hence, the simplest way to perform an update to an existing WSO2 product deployment is to use a [Helm based upgrade](https://helm.sh/docs/helm/helm_upgrade/). 40 | 41 | 1. Perform the required change(s). 42 | 43 | The following are some of the probable changes. 44 | 45 | * An update of [Helm Values](https://helm.sh/docs/chart_template_guide/values_files/) (e.g. update to the container 46 | image tag) 47 | * An update to configuration file(s) 48 | 49 | 2. Perform a Helm based upgrade. 50 | 51 | Kubernetes resources for WSO2 products utilize the most appropriate update strategy for the given scenario, depending on the involved WSO2 product profile. 52 | 53 | **Note:** 54 | > If you are not using Helm package manager to deploy WSO2 product Kubernetes resources, you may have to perform the 55 | update via Kubernetes client commands. 56 | > 57 | > For example in order to apply a configuration file change, 58 | > - Recreate the existing ConfigMap corresponding to the changed file. 59 | > - Perform a rollout to the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#updating-a-deployment) / 60 | [StatefulSet](https://kubernetes.io/docs/tutorials/stateful-application/basic-stateful-set/#rolling-update). 61 | 62 | ### Achieve zero downtime 63 | 64 | The most popular update strategy utilized by WSO2 product Kubernetes resources is of type, 65 | [rolling update](https://kubernetes.io/docs/tutorials/kubernetes-basics/update/update-intro/). Both resource types, 66 | Deployment and [StatefulSet](https://kubernetes.io/docs/tutorials/stateful-application/basic-stateful-set/#rolling-update) 67 | primarily adopt this strategy. 68 | 69 | The combined action of following factors ensure that a WSO2 product deployment maintains zero downtime during an update. 70 | 71 | * Rolling update strategy 72 | * High availability support for a given WSO2 product profile 73 | --------------------------------------------------------------------------------