Merge branch 'master' into patch-1

Author: Rodrigo Valin

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+### All Submissions:
+
+* [ ] Have you opened an Issue before filing this PR?
+* [ ] Have you signed our [CLA](https://www.mongodb.com/legal/contributor-agreement)?
+* [ ] Have you checked to ensure there aren't other open [Pull Requests](../../../pulls) for the same update/change?
+* [ ] Put `closes #XXXX` in your comment to auto-close the issue that your PR fixes (if such).
+

README.md

@@ -1,34 +1,41 @@
 # MongoDB Enterprise Kubernetes Operator #
 
-Welcome to the MongoDB Enterprise Kubernetes Operator. The Operator enables easy deploys of MongoDB into Kubernetes clusters, using our management, monitoring and backup platforms, Ops Manager and Cloud Manager. By installing this integration, you will be able to deploy MongoDB instances with a single simple command.
+Welcome to the MongoDB Enterprise Kubernetes Operator. The Operator enables easy deploy of the following applications into Kubernetes clusters:
+* MongoDB - Replica Sets, Sharded Clusters and Standalones, with authentication, TLS and many more options.
+* Ops Manager - our enterprise management, monitoring and backup platform for MongoDB. The Operator can install and manage Ops Manager in Kubernetes for you.
 
-Also the Operator allows to deploy Ops Manager into Kubernetes. Note, that currently this feature is **beta**. See more information below.
+The Operator requires access to one of our database management tools - Ops Manager or Cloud Manager - to deploy MongoDB instances. 
+You may run Ops Manager either inside or outside Kubernetes, or may use Cloud Manager (cloud.mongodb.com) instead.
 
-You can discuss this integration in our [Slack](https://community-slack.mongodb.com) - join the [#enterprise-kubernetes](https://mongo-db.slack.com/messages/CB323LCG5/) channel.
+The Operator is currently Generally Available, supported by the [MongoDB Support Team](https://support.mongodb.com/). If you need urgent help, please file a support ticket.
+For non-urgent requests, you may file a Github Issue here in the repo.
+
+You can discuss this integration in our new [Community Forum](https://community.mongodb.com/) - please use the tag [enterprise-kubernetes-operator](https://community.mongodb.com/tags/enterprise-kubernetes-operator).
 
 ## Documentation ##
 
 [Install Kubernetes Operator](https://docs.opsmanager.mongodb.com/current/tutorial/install-k8s-operator)
 
-[Deploy Standalone](https://docs.opsmanager.mongodb.com/current/tutorial/deploy-standalone)
-
-[Deploy Replica Set](https://docs.opsmanager.mongodb.com/current/tutorial/deploy-replica-set)
+[Deploy MongoDB](https://docs.mongodb.com/kubernetes-operator/stable/mdb-resources/)
 
-[Deploy Sharded Cluster](https://docs.opsmanager.mongodb.com/current/tutorial/deploy-sharded-cluster)
+[Deploy Ops Manager](https://docs.mongodb.com/kubernetes-operator/stable/om-resources/)
 
-[Edit Deployment](https://docs.opsmanager.mongodb.com/current/tutorial/edit-deployment)
+[MongoDB Resource Specification](https://docs.opsmanager.mongodb.com/current/reference/k8s-operator-specification)
 
-[Kubernetes Resource Specification](https://docs.opsmanager.mongodb.com/current/reference/k8s-operator-specification)
+[Ops Manager Resource Specification](https://docs.mongodb.com/kubernetes-operator/stable/reference/k8s-operator-om-specification/)
 
 [Troubleshooting Kubernetes Operator](https://docs.opsmanager.mongodb.com/current/reference/troubleshooting/k8s/)
 
-[Known Issues for Kubernetes Operator](https://docs.opsmanager.mongodb.com/current/reference/known-issues-k8s-beta)
+[Known Issues for Kubernetes Operator](https://docs.mongodb.com/kubernetes-operator/stable/reference/known-issues/)
 
 ## Requirements ##
 
-The MongoDB Enterprise Operator is compatible with Kubernetes v1.13 and above. It has been tested against Openshift 3.11.
+Please refer to the [Installation Instructions](https://docs.mongodb.com/kubernetes-operator/stable/tutorial/plan-k8s-operator-install/) 
+to see which Kubernetes and Openshift versions the Operator is compatible with 
 
-This Operator requires [Ops Manager](https://docs.opsmanager.mongodb.com/current/) or [Cloud Manager](https://cloud.mongodb.com/user#/cloud/login). In this document, when we refer to "Ops Manager", you may substitute "Cloud Manager". The functionality is the same.
+To work with MongoDB resource this Operator requires [Ops Manager](https://docs.opsmanager.mongodb.com/current/) (Ops Manager can 
+be installed into the same Kubernetes cluster by the Operator or installed outside of the cluster manually) 
+or [Cloud Manager](https://cloud.mongodb.com/user#/cloud/login).
 > If this is your first time trying the Operator, Cloud Manager is easier to get started
 
 
@@ -56,7 +63,7 @@ This will create a new `crd` in your cluster, `MongoDB`. This new object will be
 
 #### Operator Installation
 
-* In order to install the Operator in OpenShift, please follow [these](openshift-install.md) instructions instead.
+> In order to install the Operator in OpenShift, please follow [these](openshift-install.md) instructions instead.
 
 This operator can also be installed using yaml files, in case you are not using Helm. You may apply the config directly from github clone this repo, and apply the file
 
@@ -82,7 +89,7 @@ You need to specify the image pull secret name using `--set registry.imagePullSe
 
 Check the end of the page for instructions on how to remove the Operator.
 
-## MongoDB object ##
+## MongoDB Resource ##
 
 *This section describes how to create the MongoDB resource. Follow the next section on how to work with Ops Manager resource.*
 
@@ -91,19 +98,19 @@ Check the end of the page for instructions on how to remove the Operator.
 For the Operator to work, you will need the following information:
 
 * Base URL - the URL of an Ops Manager instance (for Cloud Manager use `https://cloud.mongodb.com`)
-* (optionally) Project Name - the name of an Ops Manager Project where MongoDBs will be deployed into. It will be 
-created by the Operator if it doesn't exist (and this is the recommended way instead of reusing the project created 
+* (optionally) Project Name - the name of an Ops Manager Project where MongoDBs will be deployed into. It will be
+created by the Operator if it doesn't exist (and this is the recommended way instead of reusing the project created
 in OpsManager directly). If omitted the name of the MongoDB resource will be used as a project name.
 * (optionally) Organization ID - the ID of the organization which the Project belongs to. The Operator will create
 an Organization with the same name as the Project if Organization ID is omitted.
 * API Credentials. This can be any pair of:
-** Public and Private Programmatic API keys. They correspond to `user` and `publicApiKey` fields in the Secret storing 
-credentials. More information about the way to create them using Ops Manager UI can be found 
+  * Public and Private Programmatic API keys. They correspond to `user` and `publicApiKey` fields in the Secret storing
+credentials. More information about the way to create them using Ops Manager UI can be found
 [here](https://docs.opsmanager.mongodb.com/current/tutorial/configure-public-api-access/#programmatic-api-keys)
-** Username and Public API key. More information about the way to create them using Ops Manager UI can be found
+  * Username and Public API key. More information about the way to create them using Ops Manager UI can be found
  [here](https://docs.opsmanager.mongodb.com/current/tutorial/configure-public-api-access/#personal-api-keys-deprecated)
 
-Note that you must whitelist the IP 
+Note that you must whitelist the IP
 range of your Kubernetes cluster so that the Operator could make API requests to Ops Manager
 
 This is documented in greater detail in our [installation guide](https://docs.opsmanager.mongodb.com/current/tutorial/install-k8s-operator)
@@ -122,53 +129,53 @@ metadata:
   name: my-project
   namespace: mongodb
 data:
-  projectName: myProjectName
+  projectName: myProjectName # this is an optional parameter
   orgId: 5b890e0feacf0b76ff3e7183 # this is an optional parameter
   baseUrl: https://my-ops-manager-or-cloud-manager-url
 ```
 > Note, that if `orgId` is skipped then the new organization named `projectName` will be automatically created and new
 project will be added there.
+> If `projectName` is skipped the project created in Ops Manager will get the same name as the MongoDB object
 
 Apply this file to create the new `Project`:
 
     kubectl apply -f my-project.yaml
 
 ### Credentials ###
 
-For a user to be able to create or update objects in this Ops Manager Project they need a Public API Key. These will be held by Kubernetes as a `Secret` object. You can create this Secret with the following command:
+For a user to be able to create or update objects in this Ops Manager Project they need either a Public API Key or a
+Programmatic API Key. These will be held by Kubernetes as a `Secret` object. You can create this Secret with the following command:
 
 ``` bash
 $ kubectl -n mongodb create secret generic my-credentials --from-literal="[email protected]" --from-literal="publicApiKey=my-public-api-key"
 ```
 
-### Creating a MongoDB Object ###
+### Creating a MongoDB Resource ###
 
-A MongoDB object in Kubernetes is a MongoDB (short name `mdb`). We are going to create a replica set to test that everything is working as expected. There is a MongoDB replica set yaml file in `samples/mongodb/minimal/replicaset.yaml`.
+A MongoDB resource in Kubernetes is a MongoDB (short name `mdb`). We are going to create a replica set to test that everything is working as expected. There is a MongoDB replica set yaml file in `samples/mongodb/minimal/replica-set.yaml`.
 
 If you have a correctly created Project with the name `my-project` and Credentials stored in a secret called `my-credentials` then, after applying this file then everything should be running and a new Replica Set with 3 members should soon appear in Ops Manager UI.
 
-    kubectl apply -f samples/mongodb/minimal/replicaset.yaml
+    kubectl apply -f samples/mongodb/minimal/replica-set.yaml
 
-## Ops Manager object (Beta) ##
+## MongoDBOpsManager Resource ##
 
-This section describes how to create the Ops Manager object in Kubernetes. Note, that this requires all
+This section describes how to create the Ops Manager Custom Resource in Kubernetes. Note, that this requires all
 the CRDs and the Operator application to be installed as described above.
 
-*Disclaimer: this is an early release of Ops Manager - so it's not recommended to use it in production*
-
 ### Create Admin Credentials Secret ###
 
-Before creating the Ops Manager object you need to prepare the information about the admin user which will be
+Before creating the Ops Manager resource you need to prepare the information about the admin user which will be
 created automatically in Ops Manager. You can use the following command to do it:
 
 ```bash
 $ kubectl create secret generic ops-manager-admin-secret  --from-literal=Username="[email protected]" --from-literal=Password="Passw0rd."  --from-literal=FirstName="Jane" --from-literal=LastName="Doe" -n <namespace>
 ```
 
 Note, that the secret is needed only during the initialization of the Ops Manager object - you can remove it or
-clean the password field after the Ops Manager object was created
+change the password using Ops Manager UI after the Ops Manager object was created
 
-### Create Ops Manager Object ###
+### Create MongoDBOpsManager Resource ###
 
 Use the file `samples/ops-manager/ops-manager.yaml`. Edit the fields and create the object in Kubernetes:
 
@@ -178,30 +185,44 @@ $ kubectl apply -f samples/ops-manager/ops-manager.yaml
 
 Note, that it takes up to 8 minutes to initialize the Application Database and start Ops Manager.
 
-### (Optionally) Create a MongoDB Object Referencing the New Ops Manager
+### (Optionally) Create a MongoDB Resource Referencing the MongoDBOpsManager
 
 Now you can use the Ops Manager application to create MongoDB objects. You need to follow the
-[instructions](https://docs.mongodb.com/kubernetes-operator/stable/tutorial/install-k8s-operator/#onprem-prerequisites)
-to prepare keys and enable network access to Ops Manager.
+[instructions](https://docs.mongodb.com/kubernetes-operator/stable/tutorial/create-operator-credentials/#prerequisites)
+to prepare keys and enable network access to Ops Manager. 
+Then you need to perform the standard steps necessary to create MongoDB resource:
+* Create a [credentials Secret](https://docs.mongodb.com/kubernetes-operator/stable/tutorial/create-operator-credentials/#create-k8s-credentials) 
+* Create a [connection ConfigMap](https://docs.mongodb.com/kubernetes-operator/stable/tutorial/create-project-using-configmap/) 
+  * Note, that you should use the value from `status.opsManager.url` in MongoDBOpsManager Resource as a value for `baseUrl` field in the ConfigMap  
+
+## Accessing Ops Manager UI (from a browser)
 
-In order to access Ops Manager UI, from outside the Kubernetes cluster (from browser), make sure you enable
-`spec.externalConnectivity` in the Ops Manager resource definition.
+In order to access Ops Manager UI, from outside the Kubernetes cluster (from a browser), make sure you enable
+`spec.externalConnectivity` in the Ops Manager resource definition. The easiest way is by configuring the LoadBalancer service type.
 
 You will be able to fetch the URL to connect to Ops Manager UI from the `Service` created by the Operator.
 
 ## Deleting the Operator ##
 
-It's important to keep correct order or removal operations. The simple rule is: **never remove Operator before mongodb resources**!
+It's important to keep correct order or removal operations. The simple rule is: **never remove Operator before MongoDB resources**!
 The reason is that the Operator cleans state in Ops Manager on deletion of the MongoDB resource in Kubernetes.
 
 These are the correct steps to remove any MongoDB Operator resources:
 
 ```bash
-# these three operations must be called first!
+# this operation must be called first!
 kubectl delete mdb --all -n <namespace>
 
 # any of the following commands must be called after removing all existing mongodb resources
 kubectl delete namespace <namespace>
 kubectl delete deployment mongodb-enterprise-operator -n <namespace>
 kubectl delete crd/mongodb.mongodb.com
+kubectl delete crd/opsmanagers.mongodb.com
+kubectl delete crd/mongodbusers.mongodb.com
 ```
+
+## Contributing
+
+Please file issues before filing PRs. For PRs to be accepted, contributors must sign our [CLA](https://www.mongodb.com/legal/contributor-agreement).
+
+Reviewers, please ensure that the CLA has been signed by referring to [the contributors tool](https://contributors.corp.mongodb.com/) (internal link).