cdk8s-plus-34 0.0.1 → 2.0.0

package/docs/plus/horizontal-pod-autoscaler.md

@@ -0,0 +1,226 @@
+# HorizontalPodAutoscaler
+
+HorizontalPodAutoscaler allows your services to scale up when demand is high and scale down when they are no longer needed.
+
+!!! tip ""
+    [API Reference](../../reference/cdk8s-plus-34/typescript.md#horizontalpodautoscaler)
+
+## Using a HorizontalPodAutoscaler
+
+The example below creates a HorizontalPodAutoscaler that scales the number of replicas of a Deployment based on the average CPU utilization of the pods.
+
+```typescript
+import * as k from 'cdk8s';
+import * as kplus from 'cdk8s-plus-34';
+
+const app = new k.App();
+const chart = new k.Chart(app, 'Chart');
+
+// Lets create a deployment for our web server
+const bookstoreWebsite = new kplus.Deployment(chart, 'BookstoreWebsite', {
+  containers: [ { image: 'node' } ],
+});
+
+// Now define a HorizontalPodAutoscaler
+const hpa = new kplus.HorizontalPodAutoscaler(chart, 'BookstoreWebsiteHpa', {
+  target: bookstoreWebsite,
+  maxReplicas: 10,
+  metrics: [
+     kplus.Metric.resourceCpu(kplus.MetricTarget.averageUtilization(70)),
+  ],
+ });
+// This will scale our website deployment up when the average CPU utilization
+// is 70% or higher up to a maximum of 10 replicas.
+```
+
+Using the example above, if our web server passes 70% CPU utilization the autoscaler will try and figure out the number of replicas to scale.
+
+The autoscaler uses the following formula:
+
+> desiredReplicas = ceil[currentReplicas * ( currentMetricValue / desiredMetricValue )]
+
+Based on this formula we can find out how many replicas will be scaled. For example if we have 1 replica and the CPU utilization is at 70%.
+
+> desiredReplicas = ceil[1 * ( 70 / 70 )] = 1
+
+The autoscaler will try and add 1 replica, meaning we'll have 2 web servers running, the original and the new replica.
+
+If the CPU utilization is 140% the autoscaler will try and provision 2 replicas. Scaling us up to 3 web servers total.
+
+> desiredReplicas = ceil[1 * ( 140 / 70 )] = 2
+
+This works the same way when scaling down.
+
+For example if our target CPU utilization is 70% and we have 3 replicas running and the CPU utilization is at 50%.
+
+> desiredReplicas = ceil[3 * ( 50 / 70 )] = 2
+
+The autoscaler will try and remove 1 replica, meaning we'll have 2 web servers running, the original and the new replica.
+
+
+## Metrics
+
+The HorizontalPodAutoscaler supports the following metrics:
+
+### Resource Metrics
+
+Resource metrics are used to scale on a resource like CPU or memory.
+
+!!! note ""
+    Since the resource usages of all the containers are summed up the total pod utilization may not accurately represent the individual container resource usage. This could lead to situations where a single container might be running with high usage and the HPA will not scale out because the overall pod usage is still within acceptable limits.
+
+
+```typescript
+import * as kplus from 'cdk8s-plus-34';
+
+
+const hpa = new kplus.HorizontalPodAutoscaler(chart, 'BookstoreWebsiteHpa', {
+  target: bookstoreWebsite,
+  maxReplicas: 10,
+  metrics: [
+     kplus.Metric.resourceCpu(kplus.MetricTarget.averageUtilization(70)),
+  ],
+ });
+```
+
+### Pods Metrics
+
+Pods metrics are used to scale on a metric describing each pod in the current scale target (for example, transactions-processed-per-second).
+
+```typescript
+import * as kplus from 'cdk8s-plus-34';
+
+
+const hpa = new kplus.HorizontalPodAutoscaler(chart, 'BookstoreWebsiteHpa', {
+  target: bookstoreWebsite,
+  maxReplicas: 10,
+  metrics: [
+     kplus.Metric.pods({
+      name: 'requests-per-second',
+      target: kplus.MetricTarget.averageUtilization(50),
+      labelSelector: kplus.LabelSelector.of({ labels: { app: 'scraper' } }),
+    }),
+  ],
+ });
+```
+
+
+## Container Metrics
+
+Container metrics are used to scale on one of the scaling target's container metrics.
+
+```typescript
+import * as kplus from 'cdk8s-plus-34';
+
+
+const hpa = new kplus.HorizontalPodAutoscaler(chart, 'BookstoreWebsiteHpa', {
+  target: bookstoreWebsite,
+  maxReplicas: 10,
+  metrics: [
+     kplus.Metric.containerMemory(kplus.MetricTarget.value(4096)),
+  ],
+ });
+```
+
+### Object Metrics
+
+Object metrics are used to scale on a metric describing a single kubernetes object (for example, requests-per-second on an Ingress object).
+
+```typescript
+import * as kplus from 'cdk8s-plus-34';
+
+
+const hpa = new kplus.HorizontalPodAutoscaler(chart, 'BookstoreWebsiteHpa', {
+  target: bookstoreWebsite,
+  maxReplicas: 10,
+  metrics: [
+     kplus.Metric.object({
+        object: ingress,
+        name: 'requests-per-second',
+        target: kplus.MetricTarget.averageUtilization(50),
+      }),
+  ],
+});
+```
+
+### External Metrics
+
+External metrics are used to scale on a metric not associated with any Kubernetes object (for example, an SQS queue).
+
+```typescript
+import * as kplus from 'cdk8s-plus-34';
+
+
+const hpa = new kplus.HorizontalPodAutoscaler(chart, 'BookstoreWebsiteHpa', {
+  target: bookstoreWebsite,
+  maxReplicas: 10,
+  metrics: [
+    kplus.Metric.external({
+      labelSelector: kplus.LabelSelector.of({ labels: { app: 'scraper' } }),
+      name: 'sqs-queue',
+      target: kplus.MetricTarget.averageUtilization(50),
+    }),
+  ],
+ });
+```
+
+## Scaling behavior
+
+The HorizontalPodAutoscaler has a few options to control the scaling behavior.
+
+### scaleUp /scaleDown
+
+The `scaleUp` / `scaleDown` options controls how fast the HorizontalPodAutoscaler scales up and down. They share the same options but have slightly different defaults.
+
+```typescript
+const hpa = new kplus.HorizontalPodAutoscaler(chart, 'BookstoreWebsiteHpa', {
+  target: bookstoreWebsite,
+  maxReplicas: 10,
+  scaleUp: {
+    stabilizationWindow: 60,
+    policies: [
+      kplus.PolicyType.pods(4),
+      kplus.PolicyType.percent(200),
+    ],
+  },
+  scaleDown: {
+    stabilizationWindow: 60,
+    policies: [
+      kplus.PolicyType.pods(2),
+      kplus.PolicyType.percent(100),
+    ],
+  },
+ });
+```
+
+| Option                | Description                                                                                                                     | `scaleUp` Default                                                                         | `scaleDown` Default                                                                        |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `stabilizationWindow` | Defines the window of past metrics that the autoscaler should consider when calculating wether or not autoscaling should occur. | 5 minutes                                                                                 | 0 (no stabilization is performed)                                                          |
+| `strategy`            | Determines if the the Autoscaler should scale as much or as little as possible.                                                 | `ScalingStrategy.MAX_CHANGE` Choose the scaling policy that will scale the most replicas. | `ScalingStrategy.MIN_CHANGE` Choose the scaling policy that will scale the least replicas. |
+| `policies`            | Defines how many replicas are scaled. Can be an absolute number or a percentage of the current replica count.                   | * Increase no more than 4 pods per 60 seconds  * Double the number of pods per 60 seconds | * Decrease to `minReplica` count (default 1)                                               |
+
+Check out the example below. We have a `scaleUp` policy that will scale up by 4 pods or double the current number of pods per 60 seconds. Because the `strategy` has been configured to `ScalingStrategy.MAX_CHANGE` the autoscaler will choose the policy that will make the most replicas.
+
+```typescript
+const hpa = new kplus.HorizontalPodAutoscaler(chart, 'BookstoreWebsiteHpa', {
+  target: bookstoreWebsite,
+  maxReplicas: 10,
+  metrics: [
+     kplus.Metric.resourceCpu(kplus.MetricTarget.averageUtilization(70)),
+  ],
+  scaleUp: {
+    strategy: kplus.ScalingStrategy.MAX_CHANGE,
+    stabilizationWindow: 60,
+    policies: [
+      kplus.PolicyType.pods(4),
+      kplus.PolicyType.percent(200),
+    ],
+  },
+ });
+```
+
+This means that if we currently have 3 web server pods, and the CPU utilization is at 72% the autoscaler will try and add 6 pods every 60 seconds.
+
+This will result in a total of 9 web server pods. If after 60 seconds the CPU utilization is still at 72% the autoscaler will only be allowed to add one more replica because `maxReplicas` has been configured to 10.
+
+For more information on HorizontalPodAutoscaler check out the [API Reference](../reference/cdk8s-plus-34/typescript.md#horizontalpodautoscaler).

package/docs/plus/ingress.md

@@ -0,0 +1,68 @@
+# Ingress
+
+[Ingress] manages external access to services in a cluster, typically through
+HTTP. Ingress may provide load balancing, SSL termination and name-based virtual
+hosting.
+
+!!! tip ""
+    [API Reference](../../reference/cdk8s-plus-34/typescript.md#ingressv1beta1)
+
+You must have an [Ingress controller] to satisfy an Ingress. Only creating an
+Ingress resource has no effect.
+
+[Ingress]: https://kubernetes.io/docs/concepts/services-networking/ingress/
+[Ingress controller]: https://kubernetes.io/docs/concepts/services-networking/ingress-controllers
+
+The following example will route HTTP requests sent to the `/hello` url prefix
+to a service associated with a deployment of the
+[hashicorp/http-echo](https://github.com/hashicorp/http-echo) image.
+
+```typescript
+import * as kplus from 'cdk8s-plus-34';
+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 helloDeployment = new kplus.Deployment(this, "Deployment", {
+      containers: [
+        {
+          image: 'hashicorp/http-echo',
+          args: [ '-text', 'hello ingress' ],
+          portNumber: 5678,
+        }
+      ]
+    });
+
+    const helloService = helloDeployment.exposeViaService({
+        ports: [
+          {
+            port: 5678,
+          }
+        ]
+      });
+
+    const ingress = new kplus.Ingress(this, 'ingress');
+    ingress.addRule('/hello', kplus.IngressBackend.fromService(helloService));
+ }
+}
+
+const app = new App();
+new MyChart(app, 'ingress');
+app.synth();
+```
+
+You can use `addHostRule(host, path, backend)` to define a route that will only
+apply to requests with this `Host` header. This can be used to implement virtual
+hosts.
+
+The `addDefaultBackend(backend)` and `addHostDefaultBackend(host, backend)`
+methods can be used to define backends that will accept all requests that do not
+match any other rules.
+
+The TCP port used to route requests to services will be determined based on
+which ports are exposed by the service (e.g. through `serve()`). If the service
+exposes multiple ports, then a port must be specified via
+`IngressBackend.fromService(service, { port })`.

package/docs/plus/job.md

@@ -0,0 +1,48 @@
+# Job
+
+Jobs are a very useful concept in kubernetes deployments.
+They can be used for add-hoc provisioning tasks, as well as long running processing jobs.
+
+In configuration, they don't differ much from regular pods, but offer some
+additional properties.
+
+!!! tip ""
+    [API Reference](../../reference/cdk8s-plus-34/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 kplus from 'cdk8s-plus-34';
+import { Construct } from 'constructs';
+import { App, Chart, ChartProps, Duration } from 'cdk8s';
+
+export class MyChart extends Chart {
+  constructor(scope: Construct, id: string, props: ChartProps = { }) {
+    super(scope, id, props);
+
+    // let's define a job spec, and set a 1 second TTL.
+    const job = new kplus.Job(this, 'LoadData', {
+      ttlAfterFinished: Duration.seconds(1)
+    });
+
+    // now add a container to all the pods created by this job
+    job.addContainer({
+      image: 'loader'
+    });
+  }
+}
+
+const app = new App();
+new MyChart(app, 'Job');
+app.synth();
+```
+
+## Scheduling
+
+See [Deployment scheduling](./deployment.md#scheduling).
+
+## Connections
+
+See [Pod connections](./pod.md#connections).

package/docs/plus/namespace.md

@@ -0,0 +1,58 @@
+# Namespace
+
+Namespaces provides a mechanism for isolating groups of resources within a single cluster.
+
+!!! tip ""
+    [API Reference](../../reference/cdk8s-plus-34/typescript.md#namespace)
+
+## Create a `Namespace`
+
+To create a new namespace in the cluster:
+
+```ts
+import * as kplus from 'cdk8s-plus-34';
+import * as k from 'cdk8s';
+
+const app = new k.App();
+const chart = new k.Chart(app, 'Chart');
+
+const namespace = new kplus.Namespace(chart, 'BackOfficeNamespace');
+```
+
+Like any other resource, if you don't specify a name, cdk8s will auto-generate one, which you
+can access by `namespace.name`.
+
+## Select namespaces
+
+Namespaces can also be selected by various mechanisms. These selections are often used in other
+cdk8s+ API's, such as [pod selection](./pod.md#pod-selection) during scheduling.
+
+### Select namespaces by name
+
+Select a namespace called `backoffice`.
+
+```ts
+import * as kplus from 'cdk8s-plus-34';
+
+const backoffice = kplus.Namespaces.select(this, 'Backoffice', { names: ['backoffice'] });
+```
+
+### Select namespace by labels
+
+Select all namespaces that have the `processing=batch` label.
+
+```ts
+import * as kplus from 'cdk8s-plus-34';
+
+const batch = kplus.Namespaces.select(this, 'Batch', { labels: { processing: 'batch'} });
+```
+
+### Select all namespaces
+
+Select all namespaces in the cluster.
+
+```ts
+import * as kplus from 'cdk8s-plus-34';
+
+const all = kplus.Namespaces.all();
+```