Merge pull request #16 from vmware-tanzu-labs/develop

v1.4.0 release

README.md

@@ -2,12 +2,96 @@
 
 ## Project Motivation
 
-- [Quick Overview](docs/OVERVIEW.md)
-- [Architecture Guide](docs/ARCHITECTURE.md)
+RPK demonstrates an end-to-end application platform running on top of
+Kubernetes. For RPK, an application platform is defined as a viable place for running
+production workloads. This is achieved by instantiating a workload orchestrator
+(Kubernetes) and running platform services on top to provide applications what
+they need to be successful in production. Technical decisions made in RPK can be used,
+ignored, replaced, or mutated based on your unique infrastructure needs. RPK
+includes a reference implementation and documentation.
 
-## License
+* **Reference Implementation**: Modular automation enabling you to deploy
+various platform services atop a Kubernetes cluster. For example, admission
+control systems or service routing systems.
 
-RPK (Reference Platform for Kubernetes), formerly referred to as "Project Ivy", is a VMware project that is developed and open sourced under the MIT License.  View the [license file](./LICENSE) and [notice file](./NOTICE) in this repo for more information.
+* **Documentation**: The documentation for RPK includes two types of assets. The
+[Architecture Guide](docs/ARCHITECTURE.md) covers each module and how it architecturally interacts
+with other components in the system. This enables the reader to understand how
+RPK has made technical decisions and to ultimately adopt or build on those
+decisions. Another is guides for cluster operators and developers. Cluster
+operations discuss how to use and interact with various platform services.
+The developer guides discuss application onboarding considerations to enable
+platform adoption.
+
+## Why is RPK Important?
+
+Kubernetes is the ubiquitous means for orchestrating containerized workloads.
+However, the path to production with Kubernetes is often misunderstood. Specifically,
+Kubernetes itself is rarely a viable place to run production workloads. Instead
+it provides a solid foundation for platform teams to deploy or build an
+application platform. Instead of viewing Kubernetes as a next-generation
+platform, we consider it to be the base to build on.
+
+![Kubernetes platform composition](docs/images/kubernetes-platform-composition.png)
+
+The above represents this common delta. For most, running Kubernetes in
+production means defining, architecting, and implementing a specific
+application platform solution. There is variance depending on the
+organization and it's maturity and team dynamics. For example, many platform teams
+wish to offer fully integrated secret management solutions, taking the onus off
+application developers to re-implement this logic in every application and ensure
+security best practices are followed. However, other teams may choose  to not
+solve this concern at the platform level. This proves the end results has
+significant variance per company. A key component to Kubernetes success is the
+flexibility/extensibility to support these organizational preferences. RPK acts
+as a reference implementation demonstrating these application platform
+concerns. However, it is expected consumers of RPK will customize it to
+fit their needs.
+
+## How Does RPK Approach Building Blocks?
+
+RPK approaches the building blocks (seen above in orange) by combining real-world
+experience and proven implementations delivered to customers. There is high variance
+in how customers approach each of these concerns, thus we take the most common
+paths seen and expect our approaches to **evolve over time**.
+
+## What Persona(s) is RPK Targeting?
+
+Kubernetes user needs fit on a spectrum, typically landing in
+one of 3 personas. Each persona envisions a slightly different path to
+production. We often identify these personas as bronze, silver, and gold.
+
+![Bronze-Silver-Gold](docs/images/bronze-silver-gold.png)
+
+* **Bronze**: I want an enterprise-grade Kubernetes distribution. This persona
+is largely interested in having the foundation poured but is not yet ready to
+build the house. In our experience, the path to production with bronze is rarely
+achieved without moving on to a silver or gold aspiration. However, the bronze
+intention may be right for the customer at the time, especially when their
+production intentions are largely non-determined.
+
+* **Silver**: I want to **create** a viable place to run applications in production
+with Kubernetes as the foundation. This persona not only wants to pour the
+foundation, but also help design, build, and operationalize an application
+platform on top - ensuring they end up with a habitable place for
+applications to live (i.e., running in production).
+
+* **Gold**: I want to **deploy** a fully-baked application platform that is
+ready for production, with Kubernetes as the foundation. This persona wants to
+adopt hardened opinions of a vendor - similar to an established housing developer,
+they can have a quality, habitable, home built. This lowers the effort seen in
+the Silver persona around architecting / building, although some extension may
+be involved.
+
+## Is RPK a VMware Product?
+
+No. The intention of RPK is to capture common implementations delivered in the
+field and make them automated and executable. This enables our architectures to
+evolve over time and be used in several contexts. RPK can be used for:
+
+* Proof-of-Concepts
+* Field implementations (as a starting point that you build atop of)
+* Internal and External Enablement
 
 ### Disclaimer
 
@@ -19,6 +103,10 @@ production ready application platform, rather give an opinionated, sample view o
 those who wish to get acquainted with Kubernetes and the decisions that go into producing a fully fledged application platform.
 Once again, the platform produced by RPK is a reference only and not intended to be production ready out of the box.
 
+## License
+
+RPK (Reference Platform for Kubernetes), formerly referred to as "Project Ivy", is a VMware project that is developed and open sourced under the MIT License.  View the [license file](./LICENSE) and [notice file](./NOTICE) in this repo for more information.
+
 ## Code of Conduct
 
 Please review our Code of Conduct prior to getting started at [CODE-OF-CONDUCT.md](CODE-OF-CONDUCT.md)

docs/ARCHITECTURE.md

@@ -1503,7 +1503,7 @@ OpenLDAP" button they are presented with a login form.
 The user credentials are provided to the OpenLDAP deployment via the
 `ldif-config` configmap.  See that configmap to get credentials for sample
 users.  This LDAP server just provides a sample identity back-end that would
-normally pre-exist at an enterprise customer.
+normally pre-exist in an enterprise environment.
 
 Enter valid credentials into the form and you will be redirected back to
 Gangway where you will find instructions to utilize your ID token.  The simplest

docs/CONTRIBUTING.md

@@ -7,10 +7,10 @@ The following is a set of guidelines for contributing to RPK.
 - [Contributing to RPK](#contributing-to-rpk)
   - [Table of Contents](#table-of-contents)
   - [General](#general)
+    - [Developer Certificate of Origin](#developer-certificate-of-origin)
     - [Relation to Tanzu Developer Center](#relation-to-tanzu-developer-center)
   - [Git](#git)
     - [Developer Workflow](#developer-workflow)
-    - [Branches > Forks](#branches--forks)
     - [Development Environment](#development-environment)
       - [Development Environment Prerequisites](#development-environment-prerequisites)
       - [Developing with a Docker Image](#developing-with-a-docker-image)
@@ -41,6 +41,12 @@ The following is a set of guidelines for contributing to RPK.
 
 ## General
 
+### Developer Certificate of Origin
+
+The Reference Platform for Kubernetes team welcomes contributions from the community. Before you start working with RPK, please read our 
+[Developer Certificate of Origin](https://cla.vmware.com/dco). All contributions to this repository must be signed as described on that page. Your signature certifies 
+that you wrote the patch or have the right to pass it on as an open-source patch.
+
 ### Relation to Tanzu Developer Center
 
 The goal of RPK is to provide a reference implementation platform which encompasses the
@@ -58,35 +64,19 @@ For more information about RPK and it's relation to TDC, view the following link
 
 The following outlines the simple developer workflow that we use for RPK.
 
-IMAGE HERE
-
 1. Contributor discovers a bug or has an idea for a new feature or an improvement to the existing processes.
-2. Contributor opens an issue and fills out all of the appropriate issue from the template.
-3. Issue is either approved, denied, or more information is requested.
-   1. Upon denial, user may attend the [Standup Meetings](#standup-meetings) or chat in the [Slack Communications Channel](#slack-communications-channel) to get issue approved.
-   2. Upon request for more information, issue will remain pending until approved.  Information should be added to the issue directly.
-   3. **NOTE:** failure to follow this process will result in your ideas, code, etc. to be revoked from admission into the repository.
-4. Contributor applies the `In Progress` label to the issue and assigns himself/herself to the issue.
-5. Contributor clones the RPK repo (e.g. `git clone [email protected]/vmware-tanzu-labs/reference-platform-kubernetes.git`).  See [Development Environment](#development-environment) for information on environment setup.
-6. Contributor creates a new branch (`e.g. git checkout -b my-cool-new-feature`) on their local development workstation.
-7. Working in the new branch on the local development workstation, the contributor modifies the code needed to address the opened and approved issue.
-8. Contributor commits and pushes the changes to the RPK repo (`e.g. git add*; git commit -a -m 'Fixes #1, my commit message'; git push --set-upstream origin my-cool-new-feature`)
-9. Contributor opens a merge request in GitLab and fills out the appropriate information in the Merge Request.
-10.  A CI pipeline is kicked off.  See [PIPELINE.md](PIPELINE.md) for more details.
+2. Contributor opens an issue.
+3. Contributor applies the `In Progress` label to the issue and assigns himself/herself to the issue.
+4. Contributor creates a fork in GitHub to their personal GitHub account.
+5. Contributor clones the RPK repo from their fork (e.g. `git clone [email protected]/<GITHUB_ID>/reference-platform-kubernetes.git`).  See [Development Environment](#development-environment) for information on environment setup.
+6. Working in the new fork on the local development workstation, the contributor modifies the code needed to address the opened and approved issue.
+7. Contributor commits and pushes the changes to their fork (`e.g. git add*; git commit -a -m 'Fixes #1, my commit message'; git push --set-upstream origin my-cool-new-feature`)
+8. Contributor opens a merge request in GitHub and fills out the appropriate information in the Merge Request.
+9. A CI pipeline is kicked off.  See [PIPELINE.md](PIPELINE.md) for more details.
    1. **NOTE:** failed CI pipeline runs will not be merged.
    2. **NOTE:** please keep commits to their individual modules (e.g. `container-registry`, or `storage`) as this helps unit test the independent modules.
-11. Once CI pipeline passes, you may remove the `WIP` from your merge request.
-12. If additional changes are requested, steps 7-8 can be repeated until the branch is approved for merge by the maintainers.
-13. Once the request approved, your code is merged!
-
-### Branches > Forks
-
-For now, we prefer branches over forks.  This allows us to do a couple things:
-
-1. **CI Pipeline Testing:**  This doesn't work with forks.
-2. **Maintainer Edits:**  Sometimes we want to make simple, quick code changes.
-
-**NOTE:** if you open a merge request from a fork, you will be asked to move to a branch instead!
+10. If additional changes are requested, steps 7-8 can be repeated until the branch is approved for merge by the maintainers.
+11. Once the request approved, your code is merged!
 
 ### Development Environment
 
@@ -221,7 +211,7 @@ For each component, we require the following structure:
 
 The following are deviances from common Ansible best practices:
 
-1. **Use of common/vars/ for variables**.  This allows us to require the variables in other roles without having to statically define variables.
+1. **Use of common/defaults/ for variables**.  This allows us to require the variables in other roles without having to statically define variables.
 2. **Use of .dependencies.yaml for module dependencies**.  This structure defines *ONLY* the modules/roles in which each role is dependent upon.
 3. **Use of clean/ sub-role**.  This role is the code to cleanup the Ansible role using `ROLE=my-role make clean.role`.
 4. **Use of demo/ sub-role**.  This role is the code to demonstrate the role (either print out info or create K8S objects) using `ROLE=my-role make demo.role`.
@@ -408,4 +398,4 @@ cool and crazy things that we can do with Ansible, however we prefer to simply u
 
 ## Questions?
 
-Please reach out in the [Standup Meetings](#standup-meetings) or chat in the [Slack Communications Channel](#slack-communications-channel)!!!
+Please open an Issue!

roles/components/core/application-pipeline/README.md

@@ -149,7 +149,3 @@ ansible-playbook -vv test.yaml \
         -e 'rpk_role_name=application-pipeline' \
         -c local -i build/inventory.yaml
 ```
-
-## Watch a Demo
-
-[Application-Pipeline Demo](https://drive.google.com/file/d/17qFo9w_VvV45OmHbmF7x3jm8tKOYVVJc/view?usp=sharing)

roles/components/extensions/tanzu-build-service/README.md

@@ -92,9 +92,5 @@ To remove the role, from the root of the repo:
 ROLE=extensions/tanzu-build-service make clean.role
 ```
 
-## Watch a Demo
-
-[Tanzu Build Service Demo](https://drive.google.com/file/d/1il9bai8dXSwCxFg0sMaLgVlZF6rjbcZt/view?usp=sharing)
-
 ## Author(s)
 [Robin Foe](mailto:[email protected])

roles/components/extensions/tanzu-mission-control/README.md

@@ -91,9 +91,5 @@ From the root of the repo:
 ROLE=product/tanzu-mission-control make clean.role
 ```
 
-## Watch a Demo
-
-[Tanzu Mission Control Demo](https://drive.google.com/file/d/1e8-rtxhRCmalLYvUBgOIzUpu0NfFIKPU/view?usp=sharing)
-
 ## Author(s)
 [Dustin Scott](mailto:[email protected])

roles/components/extensions/tanzu-observability/README.md

@@ -126,10 +126,6 @@ From the root of the repo:
 ROLE=extensions/tanzu-observability make clean.role
 ```
 
-## Watch a Demo
-
-[Tanzu Observability Demo](https://drive.google.com/file/d/1HuGRuOpSWmdMmGKhkru8nTpiz0a8Q7bO/view?usp=sharing)
-
 ## Author(s)
 [Dustin Scott](mailto:[email protected])
 

roles/components/extensions/tanzu-service-mesh/README.md

@@ -112,10 +112,6 @@ From the root of the repo:
 ROLE=extensions/tanzu-service-mesh make clean.role
 ```
 
-## Watch a Demo
-
-[Tanzu Service Mesh Demo](https://drive.google.com/file/d/19IukWLEdUGLrTv_2y3d6rXtOE0ONxkfr/view?usp=sharing)
-
 ## Author(s)
 [Andrew J. Huffman](mailto:[email protected])