chore: update cdk8s+ docs with v25 changes (#1233)

## Summary

This PR updates the cdk8s+ docs with the breaking changes introduced in Kubernetes v1.25.0. 

List of breaking changes in v25:
- https://github.com/cdk8s-team/cdk8s-plus/releases/tag/cdk8s-plus-25%2Fv2.0.0-rc.0

Parent branch PR for moving `docs/plus` files from cdk8s repo to cdk8s-plus repo:
- #1224

## Merge order

A few of my PRs touch a lot of the same code so i've documented a merge strategy. See:

- #1224

docs/plus/config-map.md

@@ -4,15 +4,15 @@ ConfigMap are used to store configuration data. They provide a dictionary based
 data structure that can be consumed in various shapes and forms.
 
 !!! tip ""
-    [API Reference](../reference/cdk8s-plus-24/typescript.md#configmap)
+    [API Reference](../../reference/cdk8s-plus-25/typescript.md#configmap)
 
 ## Use an existing `ConfigMap`
 
 You can reference to an existing `ConfigMap` like so. Note that this does not create a new object,
 and will therefore not be included in the resulting manifest.
 
 ```typescript
-import * as kplus from 'cdk8s-plus-24';
+import * as kplus from 'cdk8s-plus-25';
 
 const config: kplus.IConfigMap = kplus.ConfigMap.fromConfigMapName('config');
 
@@ -26,7 +26,7 @@ const volume = kplus.Volume.fromConfigMap(config);
 You can create config maps and add some data to them like so:
 
 ```typescript
-import * as kplus from 'cdk8s-plus-24';
+import * as kplus from 'cdk8s-plus-25';
 import * as k from 'cdk8s';
 
 const app = new k.App();
@@ -41,7 +41,7 @@ config.addData('url', 'https://my-endpoint:8080');
 Here is a nifty little trick you can use to create a volume that contains a directory on the client machine (machine that runs `cdk8s synth`):
 
 ```typescript
-import * as kplus from 'cdk8s-plus-24';
+import * as kplus from 'cdk8s-plus-25';
 import * as k from 'cdk8s';
 import * as path from 'path';
 

docs/plus/container.md

@@ -3,7 +3,7 @@
 Define containers that run in a pod using the `Container` class.
 
 !!! tip ""
-    [API Reference](../reference/cdk8s-plus-24/typescript.md#container)
+    [API Reference](../../reference/cdk8s-plus-25/typescript.md#container)
 
 ## Environment
 
@@ -15,35 +15,33 @@ Environment variables can be added to containers by specifying the
 variable name and value. The value can come from different sources, either dynamic or static.
 
 ```typescript
-import * as kplus from 'cdk8s-plus-24'
+import * as kplus from 'cdk8s-plus-25'
 
 const pod = new kplus.Pod(this, 'Pod');
 const container = pod.addContainer({
   image: 'my-app'
 });
 
 // use a static value.
-container.env.addVariable('endpoint', kplus.EnvValue.fromValue('value'));
+container.envVariables.addVariable('endpoint', kplus.EnvValue.fromValue('value'));
 
 // use a specific key from a config map.
 const backendsConfig = kplus.ConfigMap.fromConfigMapName('backends');
-container.env.addVariable('endpoint', kplus.EnvValue.fromConfigMap(backendsConfig, 'endpoint'));
+container.envVariables.addVariable('endpoint', kplus.EnvValue.fromConfigMap(backendsConfig, 'endpoint'));
 
 // use a specific key from a secret.
 const credentials = kplus.Secret.fromSecretName('credentials');
-container.env.addVariable('password', kplus.EnvValue.fromSecretValue({ secret: credentials, key: 'password' }));
+container.envVariables.addVariable('password', kplus.EnvValue.fromSecretValue({ secret: credentials, key: 'password' }));
 ```
 
-> You can pass env variables at instantiation time as well by specifying the `envVariables` property.
-
 ### Sources
 
 Environment variables can also be populated by referencing other objects as an environment source.
 With this method, all the key-value data of the source is added as environment variables,
 where the key is the env name and the value is the env value.
 
 ```ts
-import * as kplus from 'cdk8s-plus-24'
+import * as kplus from 'cdk8s-plus-25'
 
 const pod = new kplus.Pod(this, 'Pod');
 const cm = new kplus.ConfigMap(this, 'ConfigMap', {
@@ -56,7 +54,7 @@ const container = pod.addContainer({
 });
 
 // this will add 'key=value' env variable at runtime.
-container.env.copyFrom(kplus.Env.fromConfigMap(cm));
+container.envVariables.copyFrom(kplus.Env.fromConfigMap(cm));
 ```
 
 ## Volume Mounts
@@ -84,7 +82,7 @@ you would need to duplicate this configuration. This can get complex and clutter
 In contrast, here is how to do this with `cdk8s+`:
 
 ```typescript
-import * as kplus from 'cdk8s-plus-24';
+import * as kplus from 'cdk8s-plus-25';
 
 const config = kplus.ConfigMap.fromConfigMapName('config');
 const volume = kplus.Volume.fromConfigMap(config);

docs/plus/cronjob.md

@@ -4,13 +4,13 @@ CronJob resource is responsible for creating recurring [Jobs](https://kubernetes
 
 CronJob is similar to a [job](https://cdk8s.io/docs/latest/plus/job/) but it is suitable when there is a need to run a job indefinitely following a schedule. These repetitive jobs can be utilized for recurring tasks such as backing up a database, pinging a server for health checks, creating snapshots of systems and much more.
 
-!!! tip "" 
-     [API Reference](../reference/cdk8s-plus-24/typescript.md#cronjob)
+!!! tip ""
+     [API Reference](../../reference/cdk8s-plus-25/typescript.md#cronjob)
 
 ## Creating a `CronJob`
 
 ```typescript
-import * as kplus from 'cdk8s-plus-24';
+import * as kplus from 'cdk8s-plus-25';
 import { Construct } from 'constructs';
 import { App, Chart, ChartProps, Cron } from 'cdk8s';
 
@@ -42,7 +42,7 @@ app.synth();
 
 ### Defaults
 
-The above would create a cronjob resource which would schedule `databack/mysql-backup` to run every minute. With this resource, we also set some meaningful defaults. For instance, this cronjob would not run jobs concurrently by default. It will also retain 3 instance of successful job runs and 1 instance of a failed run for debugging later if needed. To customize the properties, see [API Reference](../reference/cdk8s-plus-24/typescript.md#cronjob).
+The above would create a cronjob resource which would schedule `databack/mysql-backup` to run every minute. With this resource, we also set some meaningful defaults. For instance, this cronjob would not run jobs concurrently by default. It will also retain 3 instance of successful job runs and 1 instance of a failed run for debugging later if needed. To customize the properties, see [API Reference](../../reference/cdk8s-plus-25/typescript.md#cronjob).
 
 ### Helper Functions
 
@@ -60,8 +60,8 @@ new kplus.CronJob(this, 'CronJob', {
 
 ### Validations
 
-The cronjob construct also validates some of the properties so that the manifest created works as expected. 
+The cronjob construct also validates some of the properties so that the manifest created works as expected.
 
 * You cannot pass `startingDeadline` property value less that 10 seconds. This is because the Kubernetes CronJobController checks things every 10 seconds and if the value passed is less than that then the jobs would not be scheduled.
 
-* `ttlAfterFinished` job property limits the lifetime of a job that has finished execution. You cannot pass the `ttlAfterFinished` property with any/both of the `successfulJobsRetained` and `failedJobsRetained` property since this would not let retention of jobs work in an expected manner.
+* `ttlAfterFinished` job property limits the lifetime of a job that has finished execution. You cannot pass the `ttlAfterFinished` property with any/both of the `successfulJobsRetained` and `failedJobsRetained` property since this would not let retention of jobs work in an expected manner.

docs/plus/deployment.md

@@ -3,7 +3,7 @@
 Create a deployment to govern the lifecycle and orchestration of a set of identical pods.
 
 !!! tip ""
-    [API Reference](../reference/cdk8s-plus-24/typescript.md#deployment)
+    [API Reference](../../reference/cdk8s-plus-25/typescript.md#deployment)
 
 ## Automatic pod selection
 
@@ -54,7 +54,7 @@ Following up on pod selection, you can also easily create a service that will se
 const frontends = new kplus.Deployment(chart, 'FrontEnds');
 
 // create a ClusterIP service that listens on port 9000 and redirects to port 9000 on the containers.
-frontends.expose(9000)
+frontends.exposeViaService({ port: 9000 });
 ```
 
 Notice the resulting manifest, will have the same `cdk8s.deployment` magic label as the selector.
@@ -90,7 +90,7 @@ It can be used to ensure replicas of the same workload are scheduled on differen
 
 ```ts
 import * as k from 'cdk8s';
-import * as kplus from 'cdk8s-plus-24';
+import * as kplus from 'cdk8s-plus-25';
 
 const app = new k.App();
 const chart = new k.Chart(app, 'Chart');
@@ -112,7 +112,7 @@ Here is how you can accomplish that:
 
 ```ts
 import * as k from 'cdk8s';
-import * as kplus from 'cdk8s-plus-24';
+import * as kplus from 'cdk8s-plus-25';
 
 const app = new k.App();
 const chart = new k.Chart(app, 'Chart');

docs/plus/index.md

@@ -15,8 +15,8 @@ Here is an example of how we would deploy a simple nginx container, once with th
 
 ![corevsplus](../assets/corevsplus.png)
 
-**cdk8s+** is vended as a separate library for each kubernetes spec version. The documentation presented here represents version [1.24.0](https://github.com/kubernetes/kubernetes/tree/v1.24.0/api/openapi-spec)
-and is vended as the `cdk8s-plus-24` library.
+**cdk8s+** is vended as a separate library for each kubernetes spec version. The documentation presented here represents version [1.25.0](https://github.com/kubernetes/kubernetes/tree/v1.25.0/api/openapi-spec)
+and is vended as the `cdk8s-plus-25` library.
 
 ### Naming conventions
 
@@ -26,11 +26,11 @@ and is vended as the `cdk8s-plus-24` library.
 ### Spec compatibility
 
 Per kubernetes [compatibility guarantees](https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-groups-and-versioning), **stable** resources in this library are compatible with
-any spec version higher or equal to `1.24.0`. **Non-stable** resources are not guaranteed to be compatible, as they may be removed in future spec versions.
+any spec version higher or equal to `1.25.0`. **Non-stable** resources are not guaranteed to be compatible, as they may be removed in future spec versions.
 
 !!! warning
 
-    If you are deploying manifests produced by `cdk8s-plus-24` onto clusters of a lower version, you might encounter some unsupported spec properties or invalid manifests.
+    If you are deploying manifests produced by `cdk8s-plus-25` onto clusters of a lower version, you might encounter some unsupported spec properties or invalid manifests.
 
 ## FAQ
 
@@ -78,7 +78,7 @@ manifests.
 ## At a glance
 
 ```typescript
-import * as kplus from 'cdk8s-plus-24';
+import * as kplus from 'cdk8s-plus-25';
 import * as cdk8s from 'cdk8s';
 import * as path from 'path';
 
@@ -114,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.exposeViaService({ serviceType: kplus.ServiceType.LOAD_BALANCER })
+deployment.exposeViaService({ serviceType: kplus.ServiceType.LOAD_BALANCER });
 
 // we are done, synth
 app.synth();
@@ -196,10 +196,10 @@ app.synth();
 
 === "TypeScript"
 
-    `❯ npm install cdk8s-plus-24 cdk8s constructs`
+    `❯ npm install cdk8s-plus-25 cdk8s constructs`
 
     ```typescript
-    import * as kplus from 'cdk8s-plus-24';
+    import * as kplus from 'cdk8s-plus-25';
     import * as cdk8s from 'cdk8s';
 
     const app = new cdk8s.App();
@@ -217,10 +217,10 @@ app.synth();
 
 === "JavaScript"
 
-    `❯ npm install cdk8s-plus-24 cdk8s constructs`
+    `❯ npm install cdk8s-plus-25 cdk8s constructs`
 
     ```typescript
-    const kplus = require('cdk8s-plus-24');
+    const kplus = require('cdk8s-plus-25');
     const cdk8s = require('cdk8s');
 
     const app = new cdk8s.App();
@@ -238,7 +238,7 @@ app.synth();
 
 === "Python"
 
-    `❯ pip install --pre cdk8s-plus-24 cdk8s`
+    `❯ pip install --pre cdk8s-plus-25 cdk8s`
 
     ```python
     import cdk8s_plus_22 as kplus
@@ -265,16 +265,16 @@ app.synth();
     </dependency>
     <dependency>
       <groupId>org.cdk8s</groupId>
-      <artifactId>cdk8s-plus-24</artifactId>
+      <artifactId>cdk8s-plus-25</artifactId>
       <version>2.0.0-beta.3</version>
     </dependency>
     ```
 
     ```java
     import org.cdk8s.App;
     import org.cdk8s.Chart;
-    import org.cdk8s.plus22.Deployment;
-    import org.cdk8s.plus22.ContainerProps;
+    import org.cdk8s.plus25.Deployment;
+    import org.cdk8s.plus25.ContainerProps;
 
     App app = new App();
     Chart chart = new Chart(app, "Chart");
@@ -296,17 +296,17 @@ app.synth();
       "github.com/aws/constructs-go/constructs/v10"
       "github.com/aws/jsii-runtime-go"
       "github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2"
-      "github.com/cdk8s-team/cdk8s-plus-go/cdk8splus24"
+      "github.com/cdk8s-team/cdk8s-plus-go/cdk8splus25"
     )
     ```
 
     ```go
     app := cdk8s.NewApp(nil)
     chart := cdk8s.NewChart(app, jsii.String("ubuntu"), nil)
 
-    cdk8splus24.NewDeployment(chart, jsii.String("Deployment"), &cdk8splus24.DeploymentProps{
+    cdk8splus25.NewDeployment(chart, jsii.String("Deployment"), &cdk8splus25.DeploymentProps{
       Replicas: jsii.Number(3),
-      Containers: &[]*cdk8splus24.ContainerProps{{
+      Containers: &[]*cdk8splus25.ContainerProps{{
         Image: jsii.String("ubuntu"),
       }},
     })
@@ -327,7 +327,7 @@ which are available from within **cdk8s+**, so you don't need to install an addi
 or [import](https://cdk8s.io/docs/latest/cli/import/) any resources. For example:
 
 ```ts
-import * as kplus from 'cdk8s-plus-24';
+import * as kplus from 'cdk8s-plus-25';
 import * as cdk8s from 'cdk8s';
 
 const app = new cdk8s.App();
@@ -354,3 +354,10 @@ app.synth();
 ### Missing Property
 
 See https://cdk8s.io/docs/latest/basics/escape-hatches/#patching-api-objects-behind-higher-level-apis
+
+### cdk8s+ documentation versions
+
+* [**cdk8s-plus-22**](./cdk8s-plus-22/config-map/) · Kubernetes v1.22.0
+* [**cdk8s-plus-23**](./cdk8s-plus-23/config-map/) · Kubernetes v1.23.0
+* [**cdk8s-plus-24**](./cdk8s-plus-24/config-map/) · Kubernetes v1.24.0
+* [**cdk8s-plus-25**](./cdk8s-plus-25/config-map/) · Kubernetes v1.25.0

docs/plus/ingress.md

@@ -5,7 +5,7 @@ HTTP. Ingress may provide load balancing, SSL termination and name-based virtual
 hosting.
 
 !!! tip ""
-    [API Reference](../reference/cdk8s-plus-24/typescript.md#ingressv1beta1)
+    [API Reference](../../reference/cdk8s-plus-25/typescript.md#ingressv1beta1)
 
 You must have an [Ingress controller] to satisfy an Ingress. Only creating an
 Ingress resource has no effect.
@@ -27,7 +27,7 @@ const helloDeployment = new kplus.Deployment(this, text, {
   ]
 });
 
-const helloService = helloDeployment.expose(5678);
+const helloService = helloDeployment.exposeViaService({ port: 5678 });
 
 const ingress = new Ingress(this, 'ingress');
 ingress.addRule('/hello', kplus.IngressBackend.fromService(helloService));

docs/plus/job.md

@@ -7,15 +7,15 @@ In configuration, they don't differ much from regular pods, but offer some
 additional properties.
 
 !!! tip ""
-    [API Reference](../reference/cdk8s-plus-24/typescript.md#job)
+    [API Reference](../../reference/cdk8s-plus-25/typescript.md#job)
 
 ## Delete a Job after its finished
 
 You can configure a TTL for the job after it finished its execution successfully.
 
 ```typescript
 import * as k from 'cdk8s';
-import * as kplus from 'cdk8s-plus-24';
+import * as kplus from 'cdk8s-plus-25';
 
 const app = new k.App();
 const chart = new k.Chart(app, 'Chart');

docs/plus/namespace.md

@@ -3,14 +3,14 @@
 Namespaces provides a mechanism for isolating groups of resources within a single cluster.
 
 !!! tip ""
-    [API Reference](../reference/cdk8s-plus-24/typescript.md#namespace)
+    [API Reference](../../reference/cdk8s-plus-25/typescript.md#namespace)
 
 ## Create a `Namespace`
 
 To create a new namespace in the cluster:
 
 ```ts
-import * as kplus from 'cdk8s-plus-24';
+import * as kplus from 'cdk8s-plus-25';
 import * as k from 'cdk8s';
 
 const app = new k.App();
@@ -32,7 +32,7 @@ cdk8s+ API's, such as [pod selection](./pod.md#pod-selection) during scheduling.
 Select a namespace called `backoffice`.
 
 ```ts
-import * as kplus from 'cdk8s-plus-24';
+import * as kplus from 'cdk8s-plus-25';
 
 const backoffice = kplus.Namespaces.select(this, 'Backoffice', { names: ['backoffice'] });
 ```
@@ -42,7 +42,7 @@ const backoffice = kplus.Namespaces.select(this, 'Backoffice', { names: ['backof
 Select all namespaces that have the `processing=batch` label.
 
 ```ts
-import * as kplus from 'cdk8s-plus-24';
+import * as kplus from 'cdk8s-plus-25';
 
 const batch = kplus.Namespaces.select(this, 'Batch', { labels: { processing: 'batch'} });
 ```
@@ -52,7 +52,7 @@ const batch = kplus.Namespaces.select(this, 'Batch', { labels: { processing: 'ba
 Select all namespaces in the cluster.
 
 ```ts
-import * as kplus from 'cdk8s-plus-24';
+import * as kplus from 'cdk8s-plus-25';
 
 const all = kplus.Namespaces.all();
 ```