Merge pull request #5 from stakater/service-definition

Migrate SAAP docs

.github/workflows/pull_request.yaml

@@ -7,13 +7,13 @@ on:
 
 jobs:
   qa:
-    uses: stakater/.github/.github/workflows/[email protected].29
+    uses: stakater/.github/.github/workflows/[email protected].30
     with:
       MD_CONFIG: .github/md_config.json
       DOC_SRC: content
       MD_LINT_CONFIG: .markdownlint.yaml
   build:
-    uses: stakater/.github/.github/workflows/[email protected].29
+    uses: stakater/.github/.github/workflows/[email protected].30
     with:
       DOCKER_FILE_PATH: Dockerfile
     secrets:

.github/workflows/push.yaml

@@ -7,7 +7,7 @@ on:
 
 jobs:
   push:
-    uses: stakater/.github/.github/workflows/[email protected].29
+    uses: stakater/.github/.github/workflows/[email protected].30
     with:
       DOCKER_FILE_PATH: Dockerfile
       RELEASE_BRANCH: main

.github/workflows/release.yaml

@@ -7,6 +7,6 @@ on:
 
 jobs:
   release:
-    uses: stakater/.github/.github/workflows/[email protected].29
+    uses: stakater/.github/.github/workflows/[email protected].30
     secrets:
       SLACK_WEBHOOK_URL: ${{ secrets.STAKATER_DELIVERY_SLACK_WEBHOOK }}

Dockerfile

@@ -19,7 +19,7 @@ COPY default.conf /etc/nginx/conf.d/
 # set non-root user
 USER 1001
 
-LABEL name="SAAP Documentation" \
+LABEL name="Stakater App Agility Platform (SAAP) Documentation" \
       maintainer="Stakater <[email protected]>" \
       vendor="Stakater" \
       release="1" \

README.md

@@ -1,3 +1,43 @@
-# saap-docs
+# Stakater App Agility Platform (SAAP) Documentation
 
-Stakater App Agility Platform (SAAP) Documentation
+SAAP docs are built using [MkDocs](https://github.com/mkdocs/mkdocs) which is based on Python.
+
+## GitHub Actions
+
+This repository has Github action workflow which checks the quality of the documentation and builds the Dockerfile image on Pull Requests. On a push to the main branch, it will create a GitHub release and push the built Dockerfile image to an image repository.
+
+## Build Dockerfile image and run container
+
+Build Dockerfile image:
+
+```shell
+$ docker build . -t test
+```
+
+Run container:
+
+```shell
+$ docker run -p 8080:8080 test
+```
+
+Then access the docs on [`localhost:8080`](localhost:8080).
+
+## Build locally
+
+It is preferred to build and run the docs using the Dockerfile image, however an alternative is to run the commands locally.
+
+Use [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/install.html) to set up Python virtual environments.
+
+Install [Python 3](https://www.python.org/downloads/).
+
+Install mkdocs-material and mermaid plugin:
+
+```sh
+$ pip3 install mkdocs-material mkdocs-mermaid2-plugin
+```
+
+Finally serve the docs using the built-in web server which is based on Python http server - note that the production build will use Nginx instead:
+
+```
+$ mkdocs serve
+```

content/about/cloud-providers/aws.md

@@ -1,5 +1,26 @@
 # AWS
 
+An AWS account is needed to create and manage cluster on AWS. The following criteria must be met
+
+- An account on AWS.
+- A Stakater user (ask Stakater team for the email to use for this user) with admin privileges on a separate project (Recommended). See the [required permissions](https://docs.openshift.com/container-platform/4.9/installing/installing_aws/installing-aws-account.html#installation-aws-permissions_installing-aws-account) for AWS if you do not want to grant admin privilege.
+- Resource limits must be applied on the account and the following resources must be allowed to be created.
+
+  |Type        | Limit |
+    |------------|------------|
+  | Virtual Machines | Varies. The limit should be 12 initially. (Initial deployment is 3 master + 3 infra + 3 worker)|
+  | Regional vCPUs | The limit should be A x B x 2 , where A = no. of VMS (worker + infra + master), B = vCPUs per VM) |
+  | Elastic IPs (EIPs) | 5 |
+  | Virtual Private Clouds (VPCs) | 5 |
+  | Elastic Load Balancing (ELB/NLB) | 3 |
+  | NAT Gateways | 5 |
+  | Elastic Network Interfaces (ENIs) | At least 12 |
+  | VPC Gateway| 20 |
+  | S3 buckets| 99 |
+  | Security Groups| 250|
+  | Machine Specifications | 6 machines of 8x32x120G |
+  | Region | Region will be identified by the customer |
+
 ## Instance Types
 
 SAAP offers the following worker node types and sizes on AWS:

content/about/cloud-providers/azure.md

@@ -0,0 +1,20 @@
+# Azure
+
+An azure subscription is needed to create and manage cluster on azure. The following criteria must be met
+
+- An azure subscription.
+- A Stakater user (ask Stakater team for the email to use for this user) with privileges to create an application in Azure AD (Recommended). [Create a Service Principal](https://docs.openshift.com/container-platform/4.9/installing/installing_azure/installing-azure-account.html#installation-azure-service-principal_installing-azure-account) to be used by SAAP installer if you do not want to give permissions to Azure AD.
+- Resource limits must be applied on the subscription and the following resources must be allowed to be created.
+
+  |Type        | Limit |
+  |------------|------------|
+  | Virtual Machines | Varies. The limit should be 12 initially. (Initial deployment is 3 master + 3 infra + 3 worker) |
+  | Regional vCPUs | The limit should be A x B x 2 , where A = no. of VMS (worker + infra + master), B = vCPUs per VM) |
+  | Public IP addresses | 5 |
+  | Private IP Addresses | 7 |
+  | Network Interfaces | 6 |
+  | Network Load Balancers   | 3 |
+  | Virtual Networks | 1 |
+  | StandardStorageSnapshots | 10000 (depends on how many disks are used) and backup duration |
+  | Machine Specifications | 6 machines of 8x32x120G |
+  | Region | Region will be identified by the customer |

content/about/cloud-providers/binero.md

@@ -0,0 +1,21 @@
+# Binero - OpenStack
+
+A OpenStack account is needed to create and manage cluster on Binero OpenStack. The following criteria must be met
+
+- An account on Binero.
+- A Stakater user (ask Stakater team for the email to use for this user) with admin privileges.
+- Resource limits must be applied on the account and the following resources must be allowed to be created; ask Binero support to increase the quotas as below
+
+  | Type | Limit |
+  |---|---|
+  | Instances | 100|
+  | vCPUs | 200 |
+  | RAM | 2TB |
+  | Volumes | 1000 |
+  | Snapshots | 1000 |
+  | Storage | 1000TB |
+  | Floating IPs | 10 |
+  | Security Groups | 100 |
+  | Security Groups Rules | 1000 |
+  | Ports  | 5000 |
+  | Routers | 10 |

content/about/cloud-providers/gcp.md

@@ -0,0 +1,24 @@
+# Google Cloud Platform
+
+A GCP account is needed to create and manage cluster on GCP. The following criteria must be met
+
+- An account on GCP.
+- A Stakater user (ask Stakater team for the email to use for this user) with admin privileges on a separate project (Recommended). See the [required permissions](https://docs.openshift.com/container-platform/4.9/installing/installing_gcp/installing-gcp-account.html#installation-gcp-permissions_installing-gcp-account) for GCP if you do not want to grant admin privilege.
+- Resource limits must be applied on the account and the following resources must be allowed to be created.
+
+  |Type        | Limit |
+    |------------|------------|
+  | Virtual Machines | Varies. The limit should be 12 initially. (Initial deployment is 3 master + 3 infra + 3 worker)|
+  | Regional vCPUs | The limit should be A x B x 2 , where A = no. of VMS (worker + infra + master), B = vCPUs per VM) |
+  | In-use global IP addresses | 4 |
+  | Service accounts | 5 |
+  | Firewall Rules | 11|
+  | Forwarding Rules | 2|
+  | Routers | 1|
+  | Routes | 2|
+  | Subnetworks | 2|
+  | Firewall Rules | 11|
+  | Persistent Disk SSD (GB)| 896|
+  | Target Pools | 3|
+  | Machine Specifications | 9 machines of 8x32x120G |
+  | Region | Region will be identified by the customer |

content/about/cloud-providers/overview.md

@@ -1 +1,10 @@
-# Overview
+# Supported cloud providers
+
+Stakater App Agility Platform is currently supported on following cloud providers:
+
+1. [Azure](./azure.md)
+2. [AWS](./aws.md)
+3. [Google](./gcp.md)
+4. [Binero - OpenStack](./binero.md)
+
+We support all sorts of clouds which are based on OpenStack, VMWare or BareMetals; just drop us an email at [`[email protected]`](mailto:[email protected]) if you would like to include your cloud!

content/about/onboarding.md

@@ -0,0 +1,68 @@
+# Onboarding
+
+Stakater provisions the Stakater App Agility Platform (SAAP) and takes first application to production in less than four weeks on the cloud of your choice!
+
+## Customer Data Collected
+
+This is a complete list of the customer data and permissions needed for getting started with SAAP:
+
+* Stakater asks customer if they want logging enabled - logging is optional
+* Stakater needs to know which cloud provider the customer is using
+* Stakater asks the customer what Identity Provider is used for the cloud provider
+* Stakater asks the customer to create a user in their cloud provider and download the credentials
+* Stakater asks if the customer has any preference for their cluster name
+* Stakater needs permissions to git repo access to set up pipelines - pipeline setup is optional
+
+## Week 1 - Provisioning - Free
+
+* Provision SAAP on the cloud of your choice
+    * Stakater can arrange exclusive offers with cloud providers
+* Configure access to systems
+* On-boarding session and knowledge sharing
+* Configure SSO
+
+## Week 2-4 - Application Migration - Time and Material - Optional
+
+* Select the first application or group of applications that work together
+    * Setup infrastructure and application GitOps repositories for deploying application and dependent configurations
+    * Setup tenant operator configuration and decide on the number of environments if required
+    * Divide applications into microservices and containerize them
+    * Deploy the application onto the cluster using Kubernetes Resources. List out secret required, dependent services, databases, storage requirements and implement them accordingly.
+    * Deploy Kubernetes Resources using [Stakater Developed Helm Chart](https://github.com/stakater/application) on the environment chosen - prod, stage, test, dev - in the application GitOps configuration
+    * Implement CI pipeline for the application if required. Deploy Tekton CI pipeline using the `Stakater Tekton Chart`
+    * Implement monitoring, logging, validation/testing frameworks or any additional tools for the application
+    * Validate
+* Educate team on key concepts
+
+## Next steps
+
+* Reach out to Stakater for migrating next application, or
+* Self-serviced migration of next application
+
+## Customer Responsibilities
+
+* Provide timely access to necessary people, systems, and information from relevant departments and teams
+* Thorough engagement from management and teams
+
+## Stakater Team
+
+* Dedicated team
+    * Project management: 20-40%
+    * Solution architect: 50%
+    * AppDev consultant: 100%
+
+## Output
+
+* First application live as container with cloud native CI/CD workflow
+* Up-skilled team with key concepts of cloud native containerized workflow
+
+## Customer Data Processing
+
+This is a complete list of how customer data is processed in SAAP:
+
+* Logs and events for Kubernetes resources are stored in ElasticSearch which is deployed in the customer's cluster
+* Customer's cluster is deployed in the account of the customer's cloud provider
+* Logs are retained for 7 days unless the customer requests otherwise
+* In case customer wants to forward events to a data store they can do that optionally
+* Infrastructure alerts are sent to Stakater Slack for incident management
+* Application alerts are sent to ElasticSearch and can optionally be sent to Stakater Slack if requested

content/about/release-notes.md

@@ -0,0 +1,25 @@
+# Release Notes
+
+Below is a monthly report published alongside new or updated software that details the technical features of the Stakater App Agility Platform. For new releases, these notes provide end-users with a brief summary of the features. For updates to existing products, the notes educate end-users on how the new version of the software improves upon the former.
+
+## February2022
+
+### Nexus URLs updated
+
+As part of re-organizing our add-on tools chain we updated nexus URLs.
+
+| Updated Urls                                                         |
+|----------------------------------------------------------------------|
+| `https://nexus-stakater-nexus.apps.<BASE_DOMAIN>`                    |
+| `https://nexus-docker-stakater-nexus.apps.<BASE_DOMAIN>`             |
+| `https://nexus-docker-proxy-stakater-nexus.apps.<BASE_DOMAIN>`     |
+| `https://nexus-helm-stakater-nexus.apps.<BASE_DOMAIN>/repository/helm-charts/` |
+| `https://nexus-repository-stakater-nexus.apps.<BASE_DOMAIN>/repository/` |
+| `https://nexus-stakater-nexus.apps.<BASE_DOMAIN>`                    |
+
+Following updates required to be done on workflows
+
+- Re-seal dockerconfigjson secret with updated repository URL
+- Respective Helm and docker URLs were to be updated in pipelines and code repositories
+- nexus-docker-config-forked FQDNs were updated
+- managed-addons/nexus/docker secret updated in Vault

content/about/saap-features.md

@@ -0,0 +1,34 @@
+# Stakater App Agility Platform Features
+
+## Fully managed enterprise Kubernetes
+
+* Professionally managed infrastructure
+* Automated deployment of OpenShift clusters
+* Automated scaling configuration
+* High availability and disaster recovery management
+* Storage configuration and backup management
+* Network and firewall management
+* Patch and upgrade management
+* Provision management, security, backup, network components
+* Security processes and controls aligned with industry standards.
+* Virtual network integration
+* Persistent storage volumes
+* Flexible pricing and consumption. Use existing clouds or purchase a standard cluster through Stakater.
+
+## Full-service clusters
+
+* World class support
+* Global regional availability
+* End-to-end service including building, installing, upgrading, managing, and maintaining every cluster.
+* High uptime (99.5% uptime SLA and support)
+
+## Supporting services
+
+* Automated development workflows
+* System service monitoring and log management
+* Identity and access management
+* Compliance and security policy enforcement
+* Performance and capacity management
+* Image and registry management
+
+![Stakater App Agility Platform Matrix](./images/image-1.jpg)

content/about/saap-key-differentiators.md

@@ -0,0 +1,24 @@
+# Stakater App Agility Platform Key Differentiators
+
+Stakater App Agility Platform is a true hybrid-cloud enabler. All components of Stakater App Agility Platform use common standards which can run on any cloud service, so it is easy for you to run in a hybrid environment, as well as migrate from one cloud to another. We don’t just run the platform, we enable it for you, giving you substantial Return on your Investment
+
+- We support infra nodes, i.e. we fully manage nodes that run all managed addons of your choice.
+- We manage the addons as well; and provide SLA on them.
+- We support public clouds (AWS, Azure, Google, OpenStack & VMWare) as well as on-premises.
+- Our SREs have full-stack development experience; so they understand the needs of applications and their runtimes.
+- A managed container orchestration platform is much more than making an API available: it is an environment designed with client support and acceleration in mind
+- Having a fully automated and industrialized systems management is the only way to reduce operative risks, keep costs under control, reinforce security and scale with guarantees
+- Not all managed container services are created equal – and the differences in the definition are the difference between being left alone or having a dedicated team working in solving client issues
+
+| Benefit   |  Description  |
+| -- | -- |
+| Quicker return on investment | Get up and running quickly |
+| Reduce operational overhead | Fully managed from infrastructure to day to day operations |
+| SRE support | Enhance security with automated patching and upgrades with zero downtime |
+| Empower developer productivity | Focus on developing apps that add value to the business |
+| Flexible consumption based pricing | Optimize costs with flexible pay-as-you-go pricing model (monthly binding) |
+| Avoid lock-in | SAAP can be deployed on a wide choice of IaaS platforms |
+| Sandboxed environments | Try out new ideas in a low-risk sandboxed environment |
+| Time to market | Deliver new software features faster, focusing on customer value rather than infrastructure complexities |
+| Cost reduction | Remove the cost and complexity of provisioning, managing and scaling the underlying infrastructure, OS and middleware components |
+| Efficient devops | Realise more value from your DevOps team by allowing them to focus on the 'Dev' rather than 'Ops' |

content/about/saap-vs-k8s.md

@@ -0,0 +1,33 @@
+# "SAAP or bare Kubernetes?" – The cost of building your own Kubernetes application platform
+
+SAAP is often referred to as "enterprise Kubernetes," but it can be hard to understand what that really means at first glance. Customers frequently ask,
+"SAAP or bare Kubernetes?" However, it's important to understand that SAAP already uses Kubernetes. In the overall SAAP architecture, Kubernetes provides
+both the foundation on which the SAAP platform is built and much of the tooling for running SAAP.
+
+Kubernetes is an incredibly important open-source project—one of the key projects of the Cloud Native Computing Foundation and an essential technology
+in running containers.
+
+However, the real question that potential users of SAAP might have is, "Can I just run my applications with Kubernetes alone?" Many organizations start
+by deploying Kubernetes and find that they can get a container, even an enterprise application, running in just a few days. However, as the Day-2
+operations begin, security requirements arise, and more applications are deployed, some organizations find themselves falling into the trap of building
+their own platform as a service (PaaS) with Kubernetes technology. They add an open-source ingress controller, write a few scripts to connect to their
+continuous integration/continuous deployment (CI/CD) pipelines, and then try to deploy a more complex application... and that is when the problems start.
+If deploying Kubernetes were the tip of the iceberg, then the complexity of Day-2 management would be the hidden, vast, ship-sinking bulk of that same
+iceberg under the water.
+
+While it's possible to start solving these challenges and problems, it often takes an operations team of several people, and several weeks and months of
+effort to build and maintain this "custom PaaS built on Kubernetes." This leads to inefficiency in the organization, complexity in supporting this from
+a perspective of security and certification, as well as having to develop everything from scratch when onboarding developer teams. If an organization
+were to list out all the tasks of building and maintaining this custom Kubernetes platform—that is, Kubernetes—with all the extra components needed to run
+containers successfully, they would be grouped up as follows:
+
+- **Cluster management:** This includes installing OSes, patching the OS, installing Kubernetes, configuring CNI networking, authentication integration,
+Ingress and Egress setup, persistent storage setup, hardening nodes, security patching, and configuring the underlying cloud/multicloud.
+- **Application services:** These include log aggregation, health checks, performance monitoring, security patching, container registry, and setting up
+the application staging process.
+- **Developer integration:** This includes CI/CD integration, developer tooling/IDE integration, framework integration, middleware compatibility, providing
+application performance dashboards, and RBAC.
+
+While there are many more actions and technologies that could be added to the list—most of those activities are essential for any organization to seriously
+use containers—the complexity, time, and effort in just setting all of that up is insignificant to the ongoing maintenance of those individual pieces. Each
+integration needs to be thoroughly tested, and each component and activity will have a different release cycle, security policy, and patches.