Refactor and update the docs of the repo for 1.0

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,37 @@
+---
+name: Default template
+title: ''
+labels: needs-triage
+
+---
+
+### Problem description
+
+<!--Briefly describe the issue that you've found.
+    For general questions, join us on https://pulumi-community.slack.com/. -->
+
+- I saw an issue in the following Pulumi Program: <URL>
+
+- I saw an issue in the following documentation: <URL>
+
+- I had trouble finding the information that I needed: <URL>
+
+- Other: <DETAILS>
+
+### Errors & Logs
+
+<!-- If there are any relevant error messages and logs that further describe the issue, please list them out.-->
+
+### Affected product version(s)
+
+<!-- If the issue is specific to a Pulumi product version, let us know which version(s). -->
+
+### Reproducing the issue
+
+<!-- If possible, please include a full Pulumi program tar'd or zipped up that reproduces the error. -->
+
+### Suggestions for a fix
+
+<!--If you have specific ideas about how we can fix this, let us know, or [create a pull request](https://github.com/pulumi/pulumi-kubernetes/pull/new/. :) -->
+
+<!-- To improve this template, edit the .github/ISSUE_TEMPLATE.md file -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+<!--Thanks for your contribution. See [CONTRIBUTING](CONTRIBUTING.md)
+    for Pulumi's contribution guidelines.
+
+    Help us merge your changes more quickly by adding more details such
+    as labels, milestones, and reviewers.-->
+
+### Proposed changes
+
+<!--Give us a brief description of what you've done and what it solves. -->
+
+### Related issues (optional)
+
+<!--Refer to related PRs or issues: #1234, or 'Fixes #1234' or 'Closes #1234'.
+    Or link to full URLs to issues or pull requests in other GitHub repositories. -->

CHANGELOG.md

@@ -10,6 +10,7 @@
 
 ### Improvements
 
+-   Refactor and update the docs of the repo for 1.0. (https://github.com/pulumi/pulumi-kubernetes/pull/736).
 -   Document await logic in the SDKs. (https://github.com/pulumi/pulumi-kubernetes/pull/711).
 -   Document await timeouts and how to override. (https://github.com/pulumi/pulumi-kubernetes/pull/718).
 -   Improve CustomResource for Python SDK. (https://github.com/pulumi/pulumi-kubernetes/pull/700).

CONTRIBUTING.md

@@ -1,52 +1,48 @@
 # Contributing to Pulumi
 
-Do you want to hack on Pulumi?  Awesome!  We are so happy to have you.
-
-Please refer to the [main Pulumi repo](https://github.com/pulumi/pulumi/)'s [CONTRIBUTING.md file](
-https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md) for details on how to do so.
-
 ## Building Source
 
-### Install Environment Pre-Requisites
+### Prerequisites
 
 1. Python: `python-setuptools`, `pip`, `pandoc`
 1. Go: [golangci-lint](https://github.com/golangci/golangci-lint)
 1. JS: `npm`, `yarn`
 
-### Building Source
+### Restore Vendor Dependencies
 
-1. Restore vendor dependencies:
+```
+$ make ensure
+```
 
-    ```
-    $ make ensure
-    ```
+### Build and Install
 
-1. Build, install, and link the package
+Run the following command to build and install the source.
 
-    ```
-    $ make build && make install
-    ```
+The output will be stored in `/opt/pulumi/node_modules/@pulumi/kubernetes`.
 
-    After `make` has completed, from your app directory link `@pulumi/kubernetes`:
+```bash
+$ make build && make install
+```
 
-    ```
-    $ yarn link @pulumi/kubernetes
-    ```
+`cd` into your Pulumi program directory.  After `make` has completed,
+link the recent `@pulumi/kubernetes` build from `/opt/` by running the following command:
+
+```
+$ yarn link @pulumi/kubernetes
+```
 
 ## Running Integration Tests
 
-The examples and integration tests in this repository will create and destroy real Kubernetes objects while running. Before running these tests,
-make sure that you have [configured Pulumi with your Kubernetes cluster](https://pulumi.io/install/kubernetes.html) successfully once before.
+The examples and integration tests in this repository will create and destroy
+real Kubernetes objects while running. Before running these tests, make sure that you have
+[configured Pulumi with your Kubernetes cluster](https://pulumi.io/install/kubernetes.html)
+successfully once before.
 
 You can run Kubernetes tests against `minikube` or against real Kubernetes
-clusters. Since the Pulumi Kubernetes provider uses the same client library
-as `kubectl`, if your cluster works with `kubectl`, it will also work with
-Pulumi.
-
-You must set the `KUBERNETES_CONTEXT` variable before running tests.
-The value of this environment variable should be a Kubernetes context
-which should be used when creating Kubernetes objects. If you don't have
-a context, you can create one. See the [Pulumi Kubernetes documentation](https://pulumi.io/reference/kubernetes.html) for more details on how to do this.
+clusters. Since the Pulumi Kubernetes provider uses the same
+[client-go](https://github.com/kubernetes/client-go) library as `kubectl`,
+if your cluster works with `kubectl`, it will also work with Pulumi.
 
-Once you have set `KUBERNETES_CONTEXT` and configured your cluster,
-`make test_all` will run all integration tests.
+```bash
+$ make test_all
+```

README.md

@@ -1,17 +1,228 @@
 [![Build Status](https://travis-ci.com/pulumi/pulumi-kubernetes.svg?token=eHg7Zp5zdDDJfTjY8ejq&branch=master)](https://travis-ci.com/pulumi/pulumi-kubernetes)
 
-# Kubernetes Resource Provider
+# Pulumi Kubernetes Resource Provider
 
-The Kubernetes resource provider for Pulumi lets you use Kubernetes resources in your cloud programs.
+The Kubernetes resource provider for Pulumi lets you create, deploy, and manage Kubernetes API resources and workloads in a running cluster.
 
-This package is meant for use with the Pulumi CLI.  Please visit [pulumi.io](https://pulumi.io) for
-installation instructions.
+* [Introduction](#introduction)
+  * [Kubernetes API Version Support](#kubernetes-api-version-support)
+  * [How does API support for Kubernetes work?](#how-does-api-support-for-kubernetes-work)
+* [References](#references)
+* [Prerequisites](#prerequisites)
+* [Installing](#installing)
+* [Quick Examples](#quick-examples)
+  * [Deploying a YAML Manifest](#deploying-a-yaml-manifest)
+  * [Deploying a Helm Chart](#deploying-a-helm-chart)
+  * [Deploying a Workload using the Resource API](#deploying-a-workload-using-the-resource-api)
+* [Contributing](#contributing)
+* [Code of Conduct](#code-of-conduct)
 
-## Kubernetes version support
+## Introduction
 
-The `pulumi-kubernetes` package closely tracks the latest upstream release, and provides access
-to the full API surface, including deprecated endpoints. At a minimum, we support the current version
-and the previous two versions. Older versions will likely work as well, but are not officially supported.
+`pulumi-kubernetes` provides an SDK to create any of the API resources
+available in Kubernetes.
+
+This includes the resources you know and love, such as:
+- Deployments
+- ReplicaSets
+- ConfigMaps
+- Secrets
+- Jobs etc.
+
+#### Kubernetes API Version Support
+
+The `pulumi-kubernetes` SDK closely tracks the latest upstream release, and provides access
+to the full API surface, including deprecated endpoints.
+The SDK API is 100% compatible with the Kubernetes API, and is
+schematically identical to what Kubernetes users expect.
+
+At a minimum, we support the [current Kubernetes version](https://kubernetes.io/docs/setup/release/) and the previous two versions.
+Older versions will likely work as well, but are not officially supported.
 
 See the [CHANGELOG](https://github.com/pulumi/pulumi-kubernetes/blob/master/CHANGELOG.md) for details
 on supported versions of Kubernetes for each version of the `pulumi-kubernetes` package.
+
+#### How does API support for Kubernetes work?
+
+Pulumi’s Kubernetes SDK is manufactured by automatically wrapping our
+library functionality around the Kubernetes resource [OpenAPI
+spec](https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec) as soon as a
+new version is released! Ultimately, this means that Pulumi users do not have
+to learn a new Kubernetes API model, nor wait long to work with the latest
+available versions.
+
+> Note: Pulumi also supports alpha and beta APIs.
+
+Visit the [FAQ](https://www.pulumi.com/docs/reference/clouds/kubernetes/faq/)
+for more details.
+
+## References
+
+* [Reference Documentation](https://www.pulumi.com/docs/reference/clouds/kubernetes/)
+* API Documentation
+    * [Node.js API](https://pulumi.io/reference/pkg/nodejs/@pulumi/kubernetes)
+    * [Python API](https://www.pulumi.com/docs/reference/pkg/python/pulumi_kubernetes/)
+* [All Examples](./examples)
+* [Tutorials](https://www.pulumi.com/docs/reference/tutorials/kubernetes/)
+
+## Prerequisites
+
+See the [quickstart](https://www.pulumi.com/docs/get-started/kubernetes/ ) for complete documentation.
+
+1. [Install Pulumi](https://www.pulumi.com/docs/quickstart/kubernetes/install-pulumi/)
+1. Install a language runtime such as [Node.js](https://nodejs.org/en/download) or [Python](https://www.python.org/downloads/).
+1. Install a package manager
+    * For Node.js, use [NPM](https://www.npmjs.com/get-npm) or [Yarn](https://yarnpkg.com/lang/en/docs/install).
+    * For Python, use [pip](https://pip.pypa.io/en/stable/installing/).
+1. Have access to a running Kubernetes cluster
+    * If `kubectl` already works for your running cluster, Pulumi respects and uses this configuration.
+    * If you do not have a cluster already running and available, we encourage you to
+      explore Pulumi's SDKs for AWS EKS, Azure AKS, and GCP GKE. Visit the 
+      [reference docs](https://www.pulumi.com/docs/reference/clouds/kubernetes/) for more details.
+1. [Install `kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl).
+
+## Installing
+
+This package is available in JavaScript/TypeScript for use with Node.js, as well as in Python.
+
+For Node.js use either `npm` or `yarn`:
+
+`npm`:
+
+```bash
+npm install @pulumi/kubernetes
+```
+
+`yarn`:
+
+```bash
+yarn add @pulumi/kubernetes
+```
+
+For Python use `pip`:
+
+```bash
+pip install pulumi-kubernetes
+```
+
+## Quick Examples
+
+The following examples demonstrate how to work with `pulumi-kubernetes` in
+a couple of ways.
+
+Examples may include the creation of an AWS EKS cluster, although an EKS cluster
+is **not** required to use `pulumi/kubernetes`. It is simply used to ensure
+we have access to a running Kubernetes cluster to deploy resources and workloads into.
+
+### Deploying a YAML Manifest
+
+This example deploys resources from a YAML manifest file path, using the
+transient, default `kubeconfig` credentials on the local machine, just as `kubectl` does.
+
+> Note: This capabality is primarily targeted for experimentation and transitioning 
+to Pulumi. Pulumi's [desired state model][how-pulumi-works] greatly benefits
+from having resources be directly defined in your Pulumi program as demonstrated
+in the [workload example][workload-example].
+
+```typescript
+import * as k8s as "@pulumi/kubernetes";
+
+const myApp = new k8s.yaml.ConfigFile("app", {
+    file: "app.yaml"
+});
+```
+
+### Deploying a Helm Chart
+
+This example creates an EKS cluster with [`pulumi/eks`](https://github.com/pulumi/pulumi-eks),
+and then deploys a Helm chart from the stable repo using the 
+`kubeconfig` credentials from the cluster's [Pulumi provider](https://www.pulumi.com/docs/reference/programming-model/#providers).
+
+> Note: This capabality is primarily targeted for experimentation and transitioning 
+to Pulumi. Pulumi's [desired state model][how-pulumi-works] greatly benefits
+from having resources be directly defined in your Pulumi program as demonstrated
+in the [workload example][workload-example].
+
+```typescript
+import * as eks from "@pulumi/eks";
+import * as k8s from "@pulumi/kubernetes";
+
+// Create an EKS cluster.
+const cluster = new eks.Cluster("my-cluster");
+
+// Deploy Wordpress into our cluster.
+const wordpress = new k8s.helm.v2.Chart("wordpress", {
+    repo: "stable",
+    chart: "wordpress",
+    values: {
+        wordpressBlogName: "My Cool Kubernetes Blog!",
+    },
+}, { providers: { "kubernetes": cluster.provider } });
+
+// Export the cluster's kubeconfig.
+export const kubeconfig = cluster.kubeconfig;
+```
+
+### Deploying a Workload using the Resource API
+
+This example creates a EKS cluster with [`pulumi/eks`](https://github.com/pulumi/pulumi-eks),
+and then deploys an NGINX Deployment and Service using the SDK resource API, and the 
+`kubeconfig` credentials from the cluster's [Pulumi provider](https://www.pulumi.com/docs/reference/programming-model/#providers).
+
+```typescript
+import * as eks from "@pulumi/eks";
+import * as k8s from "@pulumi/kubernetes";
+
+// Create an EKS cluster with the default configuration.
+const cluster = new eks.Cluster("my-cluster");
+
+// Create a NGINX Deployment and Service.
+const appName = "my-app";
+const appLabels = { appClass: appName };
+const deployment = new k8s.apps.v1.Deployment(`${appName}-dep`, {
+    metadata: { labels: appLabels },
+    spec: {
+        replicas: 2,
+        selector: { matchLabels: appLabels },
+        template: {
+            metadata: { labels: appLabels },
+            spec: {
+                containers: [{
+                    name: appName,
+                    image: "nginx",
+                    ports: [{ name: "http", containerPort: 80 }]
+                }],
+            }
+        }
+    },
+}, { provider: cluster.provider });
+
+const service = new k8s.core.v1.Service(`${appName}-svc`, {
+    metadata: { labels: appLabels },
+    spec: {
+        type: "LoadBalancer",
+        ports: [{ port: 80, targetPort: "http" }],
+        selector: appLabels,
+    },
+}, { provider: cluster.provider });
+
+// Export the URL for the load balanced service.
+export const url = service.status.loadBalancer.ingress[0].hostname;
+
+// Export the cluster's kubeconfig.
+export const kubeconfig = cluster.kubeconfig;
+```
+
+## Contributing
+
+If you are interested in contributing, please see the [contributing docs][contributing].
+
+## Code of Conduct
+
+You can read the code of conduct [here][code-of-conduct].
+
+[pulumi-kubernetes]: https://github.com/pulumi/pulumi-kubernetes
+[contributing]: CONTRIBUTING.md
+[code-of-conduct]: CODE-OF-CONDUCT.md
+[workload-example]: #deploying-a-workload-on-aws-eks
+[how-pulumi-works]: https://www.pulumi.com/docs/intro/concepts/how-pulumi-works

examples/README.md

@@ -0,0 +1,18 @@
+# Examples
+
+The following examples demonstrate various ways to create and work with
+Kubernetes clusters using `pulumi-kubernetes`.
+
+### Node.js
+
+1. [Run a Stateless Application Using a Deployment](https://github.com/pulumi/examples/tree/master/kubernetes-ts-nginx)
+1. [Triggering a Rollout of an App by Changing ConfigMap Data](https://github.com/pulumi/examples/tree/master/kubernetes-ts-configmap-rollout)
+1. [Deploying Jenkins on Kubernetes](https://github.com/pulumi/examples/tree/master/kubernetes-ts-jenkins)
+1. [Staged Application Rollout Gated by Prometheus Checks](https://github.com/pulumi/examples/tree/master/kubernetes-ts-staged-rollout-with-prometheus)
+1. [Kubernetes Application Deployed To Multiple Clusters ](https://github.com/pulumi/examples/tree/master/kubernetes-ts-multicloud)
+1. [Migrating Node Groups with Zero Downtime](https://www.pulumi.com/docs/reference/tutorials/kubernetes/tutorial-eks-migrate-nodegroups/)
+
+### Python
+
+1. [GKE with a Canary Deployment](https://github.com/pulumi/examples/tree/master/gcp-py-gke)
+1. [AKS with a Canary Deployment](https://github.com/pulumi/examples/tree/master/azure-py-aks)