chore: migrate docs to v2 (#923)

Resolves #872

.projenrc.js

@@ -30,7 +30,6 @@ const project = new javascript.NodeProject({
     'cdk8s-plus-22',
     'cdk8s-plus-21',
     'cdk8s-plus-20',
-    'cdk8s-plus-17',
     'constructs',
     'lerna@^4',
     'semver',
@@ -147,7 +146,6 @@ workflow.addJobs({
 // See docs/build.sh.
 const packages = [
   'cdk8s',
-  'cdk8s-plus-17',
   'cdk8s-plus-20',
   'cdk8s-plus-21',
   'cdk8s-plus-22'

docs/.pages

@@ -1,6 +1,8 @@
 nav:
   - index.md
   - getting-started.md
+  - migrating-from-1.x.md
+  - ecosystem-interoperability.md
   - concepts
   - CLI: cli
   - cdk8s+: plus

docs/build.sh

@@ -20,7 +20,7 @@ cp CHANGELOG.md docs/project/
 cp CONTRIBUTING.md docs/project/
 cp ROADMAP.md docs/project/
 
-for module in cdk8s cdk8s-plus-17 cdk8s-plus-22 cdk8s-plus-21 cdk8s-plus-20; do
+for module in cdk8s cdk8s-plus-22 cdk8s-plus-21 cdk8s-plus-20; do
   javamd=$(node -p "require.resolve('${module}/docs/java.md')")
   pythonmd=$(node -p "require.resolve('${module}/docs/python.md')")
   typescriptmd=$(node -p "require.resolve('${module}/docs/typescript.md')")

docs/cli/index.md

@@ -4,3 +4,7 @@ cdk8s is shipped with a command-line interface called `cdk8s` which can be used
 to work with cdk8s apps.
 
 The CLI is not required to use cdk8s but it includes some useful utilities.
+
+!!! notice
+
+    The documentation here relates to version `2.x` of the cdk8s toolchain, which is the latest. If you are still using version `1.x`, please refer to the [Migrating from 1.x Guide](../migrating-from-1.x.md).

docs/concepts/index.md

@@ -1,3 +1,7 @@
 # Overview
 
 This section discusses core concepts in cdk8s.
+
+!!! notice
+
+    The documentation here relates to version `2.x` of the cdk8s toolchain, which is the latest. If you are still using version `1.x`, please refer to the [Migrating from 1.x Guide](../migrating-from-1.x.md).

docs/ecosystem-interoperability.md

@@ -0,0 +1,19 @@
+# Ecosystem Interoperability
+
+As we know, there are many [CDK based libraries](http://constructs.dev/) out there, and you might want to incorporate cdk8s along side other libraries in the same application.
+
+!!! Example
+
+    For example, you can use cdk8s to define charts in an AWS CDK application, and [apply them using the EKS construct library](https://docs.aws.amazon.com/cdk/api/v1/docs/aws-eks-readme.html#cdk8s-charts).
+
+This ability, or interoperability, is based on the [constructs programming model](https://www.npmjs.com/package/constructs), which is the underlying technology on which all CDK libraries are built upon. All CDK libraries participating in the same application, must use the same major version of [constructs](https://www.npmjs.com/package/constructs), which currently has both a `3.x` and a `10.x` major version lines.
+
+In order to incorporate `cdk8s` in applications that use either version line, we need to maintain two major versions of `cdk8s`, one for each version of `constructs`.
+
+- Version `1.x` can be used along side libraries that depend on `constructs` version 3.x.
+
+    > For example: [AWS CDK v1](https://constructs.dev/search?q=aws-cdk&cdk=aws-cdk&cdkver=1&offset=0).
+
+- Version `2.x` can be used along side libraries that depend on `constructs` version 10.x.
+
+    > For example: [AWS CDK v2](https://constructs.dev/search?q=aws-cdk&cdk=aws-cdk&cdkver=2&offset=0).

docs/examples/index.md

@@ -2,3 +2,7 @@
 
 This section includes references for cdk8s and cdk8s+ examples that we have in our GitHub repository.
 Navigate to the example you like from the left side navigation panel.
+
+!!! notice
+
+    The documentation here relates to version `2.x` of the cdk8s toolchain, which is the latest. If you are still using version `1.x`, please refer to the [Migrating from 1.x Guide](../migrating-from-1.x.md).

docs/getting-started.md

@@ -227,9 +227,9 @@ Let have a look at the code:
     package main
 
     import (
-      "github.com/aws/constructs-go/constructs/v3"
+      "github.com/aws/constructs-go/constructs/v10"
       "github.com/aws/jsii-runtime-go"
-      "github.com/cdk8s-team/cdk8s-core-go/cdk8s"
+      "github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2"
     )
 
     type MyChartProps struct {
@@ -533,9 +533,9 @@ resources inspired by [paulbouwer](https://github.com/paulbouwer)'s
 
     import (
       "example.com/hello-k8s/imports/k8s"
-      "github.com/aws/constructs-go/constructs/v3"
+      "github.com/aws/constructs-go/constructs/v10"
       "github.com/aws/jsii-runtime-go"
-      "github.com/cdk8s-team/cdk8s-core-go/cdk8s"
+      "github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2"
     )
 
     type MyChartProps struct {
@@ -1127,7 +1127,7 @@ Here's how to implement `WebService`:
 
     import (
       "example.com/hello/imports/k8s"
-      "github.com/aws/constructs-go/constructs/v3"
+      "github.com/aws/constructs-go/constructs/v10"
       "github.com/aws/jsii-runtime-go"
     )
 
@@ -1203,9 +1203,9 @@ Here's how to implement `WebService`:
     package main
 
     import (
-      "github.com/aws/constructs-go/constructs/v3"
+      "github.com/aws/constructs-go/constructs/v10"
       "github.com/aws/jsii-runtime-go"
-      "github.com/cdk8s-team/cdk8s-core-go/cdk8s"
+      "github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2"
     )
 
     type MyChartProps struct {

docs/index.md

@@ -5,6 +5,10 @@ applications and reusable abstractions using familiar programming languages and
 rich object-oriented APIs. cdk8s generates pure Kubernetes YAML - you can use
 cdk8s to define applications for any Kubernetes cluster running anywhere.
 
+!!! notice
+
+    The documentation here relates to version `2.x` of the cdk8s toolchain, which is the latest. If you are still using version `1.x`, please refer to the [Migrating from 1.x Guide](./migrating-from-1.x.md).
+
 ![demo](./assets/animation.gif)
 
 Read [our blog](https://aws.amazon.com/blogs/containers/introducing-cdk-for-kubernetes/) or [watch our CNCF webinar](https://www.cncf.io/webinars/end-yaml-engineering-with-cdk8s/) to learn more and see a live demo of cdk8s in action.

docs/migrating-from-1.x.md

@@ -0,0 +1,103 @@
+# Migrating from 1.x
+
+This page describes the difference between versions `1.x` and `2.x` of the cdk8s toolchain, as well as instructions on how to migrate from one to the other.
+
+## Deprecation Timeline
+
+Version `1.x` of the cdk8s toolchain will be deprecated on 01/01/2023. After which, it will only receive critical bug fixes and security patches, but there will be no active development on it.
+
+We strongly recommend migrating to `2.x` using the instructions stated below.
+
+## Core Library
+
+Version `2.x` of the core [cdk8s](https://www.npmjs.com/package/cdk8s) library is identical to version `1.x` from an API perspective. The only difference is in the dependency they declare on the `constructs` library. This also means that the documentation and code snippets presented throughout the site is compatible with `1.x` as well, in case you'd still like to use it.
+
+!!! Tip
+
+    See [Ecosystem Interoperability](./ecosystem-interoperability.md) for reasoning behind this change.
+
+Following are instructions on what changes should be performed to use version `2.x`:
+
+=== "TypeScript"
+
+    In `package.json`, define:
+
+    ```json
+    "dependencies": {
+      "cdk8s": "^2.2.87",
+      "constructs": "^10.1.12"
+    }
+    ```
+
+=== "Java"
+
+    In `pom.xml`, define:
+
+    ```xml
+    <dependencies>
+      <dependency>
+        <groupId>org.cdk8s</groupId>
+        <artifactId>cdk8s</artifactId>
+        <version>[2.2.86,3.0]</version>
+      </dependency>
+      <dependency>
+        <groupId>software.constructs</groupId>
+        <artifactId>constructs</artifactId>
+        <version>[10.1.12,11.0.0]</version>
+      </dependency>
+    </dependencies>
+    ```
+
+=== "Python"
+
+    In `Pipfile`, define:
+
+    ```console
+    [packages]
+    constructs = "~=10.1.12"
+    cdk8s = "~=2.2.87"
+    ```
+
+=== "Go"
+
+    In `go.mod`, define:
+
+    ```go
+    require (
+      github.com/aws/constructs-go/constructs/v10 v10.1.12
+      github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2 v2.2.87
+    )
+    ```
+
+    Since major versions are encoded in go import statements, in your source code, change to:
+
+    ```go
+    import (
+      "github.com/aws/constructs-go/constructs/v10"
+      "github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2"
+    )
+    ```
+
+## CLI
+
+Version `2.x` of the [cdk8s-cli](https://www.npmjs.com/package/cdk8s-cli) is identical to version `1.x` from an API perspective. The only difference is in the project templates `cdk8s init` generates. CLI version `1.x / 2.x` will initiate projects utilizing version `1.x / 2.x` of the core library, accordingly.
+
+If you'd like to continue using version `1.x` of the CLI:
+
+=== "Homebrew"
+
+    [Locate the latest `1.x`](https://formulae.brew.sh/formula/cdk8s#default) version you'd like to install, and:
+
+    ```console
+    brew install cdk8s@1.<minor>.<patch>
+    ```
+
+=== "npm"
+    ```console
+    npm install -g cdk8s-cli@^1
+    ```
+
+=== "yarn"
+    ```console
+    yarn global add cdk8s-cli@^1
+    ```

docs/plus/index.md

@@ -7,6 +7,10 @@ Built on top of the auto-generated building blocks provided by cdk8s, this
 library includes a hand crafted *construct* for each native kubernetes object,
 exposing richer API's with reduced complexity.
 
+!!! notice
+
+    The documentation here relates to version `2.x` of the cdk8s toolchain, which is the latest. If you are still using version `1.x`, please refer to the [Migrating from 1.x Guide](../migrating-from-1.x.md).
+
 Here is an example of how we would deploy a simple nginx container, once with the low-level API (on the left), and once with the high level abstraction (on the right).
 
 ![corevsplus](../assets/corevsplus.png)
@@ -41,7 +45,7 @@ their manifests to the Kubernetes version they are operating. This way, users
 are only exposed to a set of capabilities offered by their specific cluster,
 preventing deployment errors caused by version mismatches.
 
-For example, imagine we had published a single library for all Kubernetes versions (call it `cdk8s-plus`). 
+For example, imagine we had published a single library for all Kubernetes versions (call it `cdk8s-plus`).
 This library would have had support for the [`namespaceSelector`](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#namespace-selector) property when configuring pod affinity rules. This property was only added in Kubernetes 1.21.0.
 
 Now imagine you operate Kubernetes 1.20.0. In such a case, you would have access to the `namespaceSelector` property, even though
@@ -110,7 +114,7 @@ const container = deployment.addContainer({
 container.mount(appPath, appVolume);
 
 // finally, we expose the deployment as a load balancer service and make it run
-deployment.expose(8080, {serviceType: kplus.ServiceType.LOAD_BALANCER})
+deployment.exposeViaService({ serviceType: kplus.ServiceType.LOAD_BALANCER })
 
 // we are done, synth
 app.synth();
@@ -268,9 +272,9 @@ app.synth();
 
     ```go
     import (
-      "github.com/aws/constructs-go/constructs/v3"
+      "github.com/aws/constructs-go/constructs/v10"
       "github.com/aws/jsii-runtime-go"
-      "github.com/cdk8s-team/cdk8s-core-go/cdk8s"
+      "github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2"
       "github.com/cdk8s-team/cdk8s-plus-go/cdk8splus22"
     )
     ```

docs/reference/.pages

@@ -3,5 +3,4 @@ nav:
   - cdk8s: cdk8s
   - cdk8s-plus-22: cdk8s-plus-22
   - cdk8s-plus-21: cdk8s-plus-21
-  - cdk8s-plus-20: cdk8s-plus-20
-  - cdk8s-plus-17: cdk8s-plus-17
+  - cdk8s-plus-20: cdk8s-plus-20

docs/reference/index.md

@@ -2,28 +2,27 @@
 
 This section includes API reference for the various components of cdk8s:
 
+!!! notice
+
+    The documentation here relates to version `2.x` of the cdk8s tool-chain, which is the latest. If you are still using version `1.x`, please refer to the [Migrating from 1.x Guide](../migrating-from-1.x.md)
+
 - **cdk8s**: Core library
     - [TypeScript](./cdk8s/typescript.md)
     - [Python](./cdk8s/python.md)
     - [Java](./cdk8s/java.md)
     - [Go](./cdk8s/go.md)
 - **cdk8s-plus-22**: Intent-based APIs for Kubernetes resources. (spec version [1.22.0](https://github.com/kubernetes/kubernetes/tree/v1.22.0/api/openapi-spec))
-    - [TypeScript](./cdk8s-plus-17/typescript.md)
-    - [Python](./cdk8s-plus-17/python.md)
-    - [Java](./cdk8s-plus-17/java.md)
-    - [Go](./cdk8s-plus-17/go.md)
+    - [TypeScript](./cdk8s-plus-22/typescript.md)
+    - [Python](./cdk8s-plus-22/python.md)
+    - [Java](./cdk8s-plus-22/java.md)
+    - [Go](./cdk8s-plus-22/go.md)
 - **cdk8s-plus-21**: Intent-based APIs for Kubernetes resources. (spec version [1.21.0](https://github.com/kubernetes/kubernetes/tree/v1.21.0/api/openapi-spec))
-    - [TypeScript](./cdk8s-plus-17/typescript.md)
-    - [Python](./cdk8s-plus-17/python.md)
-    - [Java](./cdk8s-plus-17/java.md)
-    - [Go](./cdk8s-plus-17/go.md)
+    - [TypeScript](./cdk8s-plus-21/typescript.md)
+    - [Python](./cdk8s-plus-21/python.md)
+    - [Java](./cdk8s-plus-21/java.md)
+    - [Go](./cdk8s-plus-21/go.md)
 - **cdk8s-plus-20**: Intent-based APIs for Kubernetes resources. (spec version [1.20.0](https://github.com/kubernetes/kubernetes/tree/v1.20.0/api/openapi-spec))
-    - [TypeScript](./cdk8s-plus-17/typescript.md)
-    - [Python](./cdk8s-plus-17/python.md)
-    - [Java](./cdk8s-plus-17/java.md)
-    - [Go](./cdk8s-plus-17/go.md)
-- **cdk8s-plus-17**: Intent-based APIs for Kubernetes resources. (spec version [1.17.0](https://github.com/kubernetes/kubernetes/tree/v1.17.0/api/openapi-spec))
-    - [TypeScript](./cdk8s-plus-17/typescript.md)
-    - [Python](./cdk8s-plus-17/python.md)
-    - [Java](./cdk8s-plus-17/java.md)
-    - [Go](./cdk8s-plus-17/go.md)
+    - [TypeScript](./cdk8s-plus-20/typescript.md)
+    - [Python](./cdk8s-plus-20/python.md)
+    - [Java](./cdk8s-plus-20/java.md)
+    - [Go](./cdk8s-plus-20/go.md)

examples/go/crd/go.mod

@@ -3,7 +3,7 @@ module example.com/crd-go
 go 1.16
 
 require (
-	github.com/aws/constructs-go/constructs/v3 v3.3.107
-	github.com/aws/jsii-runtime-go v1.32.0
-	github.com/cdk8s-team/cdk8s-core-go/cdk8s v1.0.0-beta.26
+	github.com/aws/constructs-go/constructs/v10 v10.1.12
+	github.com/aws/jsii-runtime-go v1.59.0
+	github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2 v2.2.87
 )