cdk8s-plus-32 2.0.0

package/docs/plus/config-map.md

@@ -0,0 +1,98 @@
+# ConfigMap
+
+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-32/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-32';
+import { Construct } from 'constructs';
+import { App, Chart, ChartProps } from 'cdk8s';
+
+export class MyChart extends Chart {
+  constructor(scope: Construct, id: string, props?: ChartProps) {
+    super(scope, id, props);
+
+    const config: kplus.IConfigMap = kplus.ConfigMap.fromConfigMapName(this, 'ConfigMap', 'config');
+
+    // the 'config' constant can later be used by API's that require an IConfigMap.
+    // for example when creating a volume.
+    kplus.Volume.fromConfigMap(this, 'Volume', config);
+  }
+}
+
+const app = new App();
+new MyChart(app, 'VolumeFromConfigMap');
+app.synth();
+```
+
+## Adding data
+
+You can create config maps and add some data to them like so:
+
+```typescript
+import * as kplus from 'cdk8s-plus-32';
+import { Construct } from 'constructs';
+import { App, Chart, ChartProps } from 'cdk8s';
+
+export class MyChart extends Chart {
+  constructor(scope: Construct, id: string, props?: ChartProps) {
+    super(scope, id, props);
+
+    const config = new kplus.ConfigMap(this, 'Config');
+    config.addData('url', 'https://my-endpoint:8080');
+  }
+}
+
+const app = new App();
+new MyChart(app, 'ConfigMap');
+app.synth();
+```
+
+## Creating a volume from a directory
+
+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-32';
+import * as path from 'path';
+import { Construct } from 'constructs';
+import { App, Chart, ChartProps } from 'cdk8s';
+
+export class MyChart extends Chart {
+  constructor(scope: Construct, id: string, props?: ChartProps) {
+    super(scope, id, props);
+    const appMap = new kplus.ConfigMap(this, 'Config');
+
+    // add the files in the directory to the config map.
+    // this will create a key for each file.
+    // note: this directory needs to exist
+    // note: that only top level files will be included, sub-directories are not yet supported.
+    appMap.addDirectory(path.join(__dirname, 'app'));
+
+    const appVolume = kplus.Volume.fromConfigMap(this, 'ConfigMap', appMap);
+
+    const mountPath = '/var/app';
+    const pod = new kplus.Pod(this, 'Pod');
+    const container = pod.addContainer({
+      image: 'node',
+      command: [ 'node', 'app.js' ],
+      workingDir: mountPath,
+    });
+
+    // from here, just mount the volume to a container, and run your app!
+    container.mount(mountPath, appVolume);
+  }
+}
+
+const app = new App();
+new MyChart(app, 'AppWithDir');
+app.synth();
+```

package/docs/plus/container.md

@@ -0,0 +1,133 @@
+# Container
+
+Define containers that run in a pod using the `Container` class.
+
+!!! tip ""
+    [API Reference](../../reference/cdk8s-plus-32/typescript.md#container)
+
+## Environment
+
+A container's environment can be populated by various methods.
+
+### Variables
+
+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-32';
+import { Construct } from 'constructs';
+import { App, Chart, ChartProps } from 'cdk8s';
+
+export class MyChart extends Chart {
+  constructor(scope: Construct, id: string, props: ChartProps = { }) {
+    super(scope, id, props);
+
+    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'));
+
+    // use a specific key from a config map.
+    const backendsConfig = kplus.ConfigMap.fromConfigMapName(this, 'BackendConfig', 'backends');
+    container.env.addVariable('endpoint', kplus.EnvValue.fromConfigMap(backendsConfig, 'endpoint'));
+
+    // use a specific key from a secret.
+    const credentials = kplus.Secret.fromSecretName(this, 'Credentials', 'credentials');
+    container.env.addVariable('password', kplus.EnvValue.fromSecretValue({ secret: credentials, key: 'password' }));
+  }
+}
+
+const app = new App();
+new MyChart(app, 'container');
+app.synth();
+```
+
+### 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.
+
+```typescript
+const pod = new kplus.Pod(this, 'Pod');
+const cm = new kplus.ConfigMap(this, 'ConfigMap', {
+  data: {
+    key: 'value',
+  }
+});
+const container = pod.addContainer({
+  image: 'my-app'
+});
+
+// this will add 'key=value' env variable at runtime.
+container.env.copyFrom(kplus.Env.fromConfigMap(cm));
+```
+
+## Volume Mounts
+
+A very common capability is to mount a volume with some data onto a container. Using pure kubernetes API, this would require writing something like:
+
+```yaml
+kind: Pod
+apiVersion: v1
+spec:
+  containers:
+    - name: main
+      volumeMounts:
+        - mountPath: /path/to/mount
+          name: 'config-volume'
+  volumes:
+    - name: 'config-volume'
+      configMap:
+        name: 'config'
+```
+
+Notice the apparent redundancy of having to specify the volume name twice. Also, if you happen to need the same mount in other pods,
+you would need to duplicate this configuration. This can get complex and cluttered very fast.
+
+In contrast, here is how to do this with `cdk8s+`:
+
+```typescript
+const config = kplus.ConfigMap.fromConfigMapName(this, 'Config', 'config');
+const volume = kplus.Volume.fromConfigMap(this, 'Volume', config);
+
+const pod = new kplus.Pod(this, 'Pod');
+const container = pod.addContainer({
+  image: 'my-app'
+})
+
+// Cool alert: every pod that will later be configured with this container,
+// will automatically have access to this volume, so you don't need to explicitly add it to the pod spec!.
+container.mount('/path/to/mount', volume);
+```
+
+## Probes
+
+A [Probe] is a diagnostic performed periodically by the kubelet on a Container. To
+perform a diagnostic, the kubelet calls a Handler implemented by the container.
+
+[Probe]: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#probe-v1-core
+
+A `Probe` instance can be created through one of the `fromXxx` static methods:
+
+- `Probe.fromHttpGet()`
+- `Probe.fromCommand()`
+
+Readiness, liveness, and startup probes can be configured at the container-level through the `readiness`, `liveness`, and `startup` options:
+
+```typescript
+new kplus.Pod(this, 'Pod', {
+  containers: [
+    {
+      image: 'my-app',
+      readiness: kplus.Probe.fromHttpGet('/ping'),
+    }
+  ]
+});
+```
+
+See the API reference for details.

package/docs/plus/cronjob.md

@@ -0,0 +1,67 @@
+# CronJob
+
+CronJob resource is responsible for creating recurring [Jobs](https://kubernetes.io/docs/concepts/workloads/controllers/job/). The job recurrence is determined by a [Cron](https://github.com/cdk8s-team/cdk8s-core/blob/2.x/src/cron.ts) expression.
+
+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-32/typescript.md#cronjob)
+
+## Creating a `CronJob`
+
+```typescript
+import * as kplus from 'cdk8s-plus-32';
+import { Construct } from 'constructs';
+import { App, Chart, ChartProps, Cron } from 'cdk8s';
+
+export class MyChart extends Chart {
+  constructor(scope: Construct, id: string, props: ChartProps = { }) {
+    super(scope, id, props);
+
+    new kplus.CronJob(this, 'CronJob', {
+      containers: [{
+        image: 'databack/mysql-backup',
+      }],
+      // You can pass a custom cron schedule using our Cron class
+      schedule: Cron.schedule({
+        minute: '*',
+        hour: '*',
+        day: '*',
+        month: '*',
+        weekDay: '*',
+      }),
+    });
+  }
+}
+
+const app = new App();
+new MyChart(app, 'cronjob-readme');
+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-32/typescript.md#cronjob).
+
+### Helper Functions
+
+As we see in the previous example, we can pass custom cron expression for scheduling our jobs. But, we have also have added helper functions that would make it easy to mention some of the commonly used schedules. These include scheduling jobs to run every minute, hour, day, week, month or year. For instance, the same example mentioned before could be written as,
+
+```typescript
+new kplus.CronJob(this, 'CronJob', {
+  containers: [{
+    image: 'databack/mysql-backup',
+  }],
+  // This would schedule jobs to be scheduled to run every minute
+  schedule: Cron.everyMinute(),
+});
+```
+
+### Validations
+
+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.

package/docs/plus/deployment.md

@@ -0,0 +1,232 @@
+# Deployment
+
+Create a deployment to govern the lifecycle and orchestration of a set of identical pods.
+
+!!! tip ""
+    [API Reference](../../reference/cdk8s-plus-32/typescript.md#deployment)
+
+## Automatic pod selection
+
+When you specify pods in a deployment, you normally have to configure the appropriate labels and selectors to
+make the deployment control the relevant pods. This construct does this automatically.
+
+```typescript
+import * as kplus from 'cdk8s-plus-32';
+import { Construct } from 'constructs';
+import { App, Chart, ChartProps } from 'cdk8s';
+
+export class MyChart extends Chart {
+  constructor(scope: Construct, id: string, props: ChartProps = { }) {
+    super(scope, id, props);
+
+    new kplus.Deployment(this, 'FrontEnds', {
+      containers: [ { image: 'node' } ],
+    });
+  }
+}
+
+const app = new App();
+new MyChart(app, 'deployment');
+app.synth();
+```
+
+Note the resulting manifest contains a special `cdk8s.io/metadata.addr` label that is applied to the pods, and is used as
+the selector for the deployment.
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deployment-frontends-c8e48310
+spec:
+  minReadySeconds: 0
+  progressDeadlineSeconds: 600
+  replicas: 2
+  selector:
+    matchLabels:
+      cdk8s.io/metadata.addr: deployment-FrontEnds-c89e9e97
+  strategy:
+    rollingUpdate:
+      maxSurge: 25%
+      maxUnavailable: 25%
+    type: RollingUpdate
+  template:
+    metadata:
+      labels:
+        cdk8s.io/metadata.addr: deployment-FrontEnds-c89e9e97
+    spec:
+      automountServiceAccountToken: false
+      containers:
+        - image: node
+          imagePullPolicy: Always
+          name: main
+          resources:
+            limits:
+              cpu: 1500m
+              memory: 2048Mi
+            requests:
+              cpu: 1000m
+              memory: 512Mi
+          securityContext:
+            allowPrivilegeEscalation: false
+            privileged: false
+            readOnlyRootFilesystem: true
+            runAsGroup: 26000
+            runAsNonRoot: true
+            runAsUser: 25000
+      dnsPolicy: ClusterFirst
+      restartPolicy: Always
+      securityContext:
+        fsGroupChangePolicy: Always
+        runAsNonRoot: true
+      setHostnameAsFQDN: false
+```
+
+## Exposing via a service
+
+Following up on pod selection, you can also easily create a service that will select the pods relevant to the deployment.
+
+```typescript
+// store the deployment to created in a constant
+const frontends = new kplus.Deployment(this, 'FrontEnds', {
+  containers: [ {
+    image: 'node',
+    portNumber: 9000,
+  } ],
+});
+
+// create a ClusterIP service that listens on port 9000 and redirects to port 9000 on the containers.
+frontends.exposeViaService({ ports: [{
+  port: 9000,
+}]
+});
+```
+
+Notice the resulting manifest, will have the same `cdk8s.io/metadata.addr` magic label as the selector.
+This will cause the service to attach to the pods that were configured as part of the said deployment.
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deployment-frontends-c8e48310
+spec:
+  minReadySeconds: 0
+  progressDeadlineSeconds: 600
+  replicas: 2
+  selector:
+    matchLabels:
+      cdk8s.io/metadata.addr: deployment-FrontEnds-c89e9e97
+  strategy:
+    rollingUpdate:
+      maxSurge: 25%
+      maxUnavailable: 25%
+    type: RollingUpdate
+  template:
+    metadata:
+      labels:
+        cdk8s.io/metadata.addr: deployment-FrontEnds-c89e9e97
+    spec:
+      automountServiceAccountToken: false
+      containers:
+        - image: node
+          imagePullPolicy: Always
+          name: main
+          ports:
+            - containerPort: 9000
+          resources:
+            limits:
+              cpu: 1500m
+              memory: 2048Mi
+            requests:
+              cpu: 1000m
+              memory: 512Mi
+          securityContext:
+            allowPrivilegeEscalation: false
+            privileged: false
+            readOnlyRootFilesystem: true
+            runAsGroup: 26000
+            runAsNonRoot: true
+            runAsUser: 25000
+          startupProbe:
+            failureThreshold: 3
+            tcpSocket:
+              port: 9000
+      dnsPolicy: ClusterFirst
+      restartPolicy: Always
+      securityContext:
+        fsGroupChangePolicy: Always
+        runAsNonRoot: true
+      setHostnameAsFQDN: false
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: deployment-frontends-service-c8206158
+spec:
+  externalIPs: []
+  ports:
+    - port: 9000
+  selector:
+    cdk8s.io/metadata.addr: deployment-FrontEnds-c89e9e97
+  type: ClusterIP
+```
+
+## Scheduling
+
+In addition to the scheduling capabilities provided by [pod scheduling](./pod.md#scheduling),
+a Deployment offers the following:
+
+### Spreading
+
+A spread is a [separation](./pod.md#pod-separation) of pods from themselves.
+It can be used to ensure replicas of the same workload are scheduled on different topologies.
+
+> The same API is also available on all workload resources (i.e `Deployment`, `StatefulSet`, `Job`, `DaemonSet`).
+
+```typescript
+const redis = new kplus.Deployment(this, 'Redis', {
+  containers: [{ image: 'redis' }],
+  replicas: 3,
+});
+
+redis.scheduling.spread({
+  topology: kplus.Topology.HOSTNAME
+});
+```
+
+This example ensures that each replica of the `Redis` deployment
+will be scheduled on a different node.
+
+Take, for [example](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#more-practical-use-cases), a three-node cluster running a web application with an in-memory cache like redis. You'd like to co-locate the web servers with the cache as much as possible, while still maintaining node failure resistance. (i.e not all pods are on the same node).
+
+Here is how you can accomplish that:
+
+```typescript
+const redis = new kplus.Deployment(this, 'Redis', {
+  containers: [{ image: 'redis' }],
+  replicas: 3,
+});
+
+const web = new kplus.Deployment(this, 'Web', {
+  containers: [{ image: 'web' }],
+  replicas: 3,
+});
+
+// ensure redis is spread across all nodes
+redis.scheduling.spread({
+  topology: kplus.Topology.HOSTNAME
+});
+
+// ensure web app is spread across all nodes
+web.scheduling.spread({
+  topology: kplus.Topology.HOSTNAME
+});
+
+// ensure a web app pod always runs along side a cache instance
+web.scheduling.colocate(redis);
+```
+
+## Connections
+
+See [Pod connections](./pod.md#connections).