cdk8s-plus-31 2.0.0

package/docs/plus/rbac.md

@@ -0,0 +1,104 @@
+# Role Based Access Control
+
+Role Based Access Control(RBAC) helps you restrict actions that can be performed on specific Kubernetes resources. To make this possible, RBAC lets you create roles with rules which define access permissions for your specified resource.
+
+These roles can then be binded to Kubernetes subjects, which could be User, Group or ServiceAccount.
+
+!!! note
+    Rules or permissions are purely additive and there are no deny rules.
+
+Now, there are two types of roles available,
+* Role: These set permissions within a particular namespace i.e. is for namespaced resources, like, pods, deployments.
+* ClusterRole: These set permissions for non-namespaced resources, like, nodes, urls.
+
+and, similarly there are two types of binding available,
+* RoleBinding: These grant permissions within a specific namespace.
+* ClusterRoleBinding: These grant cluster wide permissions .
+
+!!! tip "Learn more"
+    * [Role API Reference](../../reference/cdk8s-plus-31/typescript.md#role)
+    * [RoleBinding API Reference](../../reference/cdk8s-plus-31/typescript.md#role-binding)
+
+## Role
+
+### Create role and add rules to it
+
+```typescript
+import * as kplus from 'cdk8s-plus-31';
+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);
+
+    // Creating RBAC Role
+    const role = new kplus.Role(this, 'SampleRole');
+
+    // The convenience method here `allowReadWrite` would add
+    // `get, list, watch, create, update, patch, delete,
+    // deletecollection` rules to the role for deployment resources.
+    role.allowReadWrite(kplus.ApiResource.DEPLOYMENTS);
+
+    const user = kplus.User.fromName(this, 'SampleUser', 'Jane');
+    const group = kplus.Group.fromName(this, 'SampleGroup', 'sample-group');
+    const serviceAccount = new kplus.ServiceAccount(this, 'SampleServiceAccount');
+
+    // You can bind this role to a specific user, group or service account
+    role.bind(user, group, serviceAccount);
+  }
+}
+
+const app = new App();
+new MyChart(app, 'rbac-docs');
+app.synth();
+```
+
+## ClusterRole
+
+### Create ClusterRole and add rules to it
+
+```typescript
+// Creating RBAC ClusterRole
+const clusterRole = new kplus.ClusterRole(this, 'SampleClusterRole');
+
+// Adding list of rules to the ClusterRole for 'Nodes' and 'URL' non-namespaced resource
+clusterRole.allowReadWrite(kplus.ApiResource.NODES, kplus.NonApiResource.of('/healthz'));
+
+const user = kplus.User.fromName(this, 'SampleUser', 'Jane');
+const group = kplus.Group.fromName(this, 'SampleGroup', 'sample-group');
+const serviceAccount = new kplus.ServiceAccount(this, 'SampleServiceAccount');
+
+// You can bind this cluster role to a specific user, group or service account
+clusterRole.bind(user, group, serviceAccount);
+```
+
+## Resource Permission Methods
+
+You can use convenience methods like `grantRead` and `grantReadWrite` which would make it easier to grant list of subjects set of permissions for the resource.
+
+### `grantReadWrite` Method
+
+```typescript
+// Creating a Pod resource
+const pod = new kplus.Pod(this, 'Pod', {
+    containers: [{ image: 'image' }],
+});
+
+const user = kplus.User.fromName(this, 'SampleUser', 'Jane');
+const group = kplus.Group.fromName(this, 'SampleGroup', 'sample-group');
+const serviceAccount = new kplus.ServiceAccount(this, 'SampleServiceAccount');
+
+// You can grant permissions to specific user, group or service account.
+pod.permissions.grantReadWrite(user, group, serviceAccount);
+```
+
+## Add subjects to an already bound role
+
+```typescript
+const user = kplus.User.fromName(this, 'SampleUser', 'Jane');
+const binding = role.bind(user);
+
+const anotherUser = kplus.User.fromName(this, 'AnotherSampleUser', 'James');
+binding.addSubjects(anotherUser);
+```

package/docs/plus/secret.md

@@ -0,0 +1,32 @@
+# Secret
+
+Secrets are used to store confidential information. Never store such information on the definition of the pod itself.
+
+!!! tip ""
+    [API Reference](../../reference/cdk8s-plus-31/typescript.md#secret)
+
+## Use an existing `Secret`
+
+To reference a secret created outside of your deployment definition, use the following. 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-31';
+
+const secret = kplus.Secret.fromSecretName('aws-creds');
+```
+
+## Adding data
+
+To create a new secret with some data, use:
+
+```typescript
+import * as kplus from 'cdk8s-plus-31';
+import * as k from 'cdk8s';
+
+const app = new k.App();
+const chart = new k.Chart(app, 'Chart');
+
+const secret = new kplus.Secret(chart, 'Secret');
+secret.addStringData('password', 'some-encrypted-data');
+```

package/docs/plus/service-account.md

@@ -0,0 +1,35 @@
+# ServiceAccount
+
+Use service accounts to provide an identity for pods.
+
+!!! tip ""
+    [API Reference](../../reference/cdk8s-plus-31/typescript.md#serviceaccount)
+
+## Use an existing `ServiceAccount`
+
+To reference a service account created outside of your deployment definition, use the following. 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-31';
+
+const serviceAccount = kplus.ServiceAccount.fromServiceAccountName('aws-service');
+```
+
+## Allowing access to secrets
+
+To create a new service account, and give it access to some secrets, use the following:
+
+```typescript
+import * as kplus from 'cdk8s-plus-31';
+import * as k from 'cdk8s';
+
+const app = new k.App();
+const chart = new k.Chart(app, 'Chart');
+
+const awsCreds = kplus.Secret.fromSecretName('aws-creds');
+const awsService = new kplus.ServiceAccount(chart, 'AWS');
+
+// give access to the aws creds secret.
+awsService.addSecret(awsCreds);
+```

package/docs/plus/service.md

@@ -0,0 +1,41 @@
+# Service
+
+Use services when you want to expose a set of pods using a stable network
+identity. They can also be used for externalizing endpoints to clients outside
+of the kubernetes cluster.
+
+!!! tip ""
+    [API Reference](../../reference/cdk8s-plus-31/typescript.md#service)
+
+## Selectors
+
+Services must be configured with selectors that tell it which pods should it serve.
+The most common selector method is using labels.
+
+```typescript
+import * as k from 'cdk8s';
+import * as kplus from 'cdk8s-plus-31';
+
+const app = new k.App();
+const chart = new k.Chart(app, 'Chart');
+const frontends = new kplus.Service(chart, 'FrontEnds');
+
+// this will cause the service to select all pods with the 'run: frontend' label.
+frontends.select(kplus.LabelSelector.equals('run', 'frontend'));
+```
+
+## Ports
+
+Ports that the service will listen and redirect to can be configured like so:
+
+```typescript
+import * as k from 'cdk8s';
+import * as kplus from 'cdk8s-plus-31';
+
+const app = new k.App();
+const chart = new k.Chart(app, 'Chart');
+const frontends = new kplus.Service(chart, 'FrontEnds');
+
+// make the service bind to port 9000 and redirect to port 80 on the associated containers.
+frontends.bind({port: 9000, targetPort: 80)
+```

package/docs/plus/volume.md

@@ -0,0 +1,38 @@
+# Volume
+
+Volume represents a named volume in a pod that may be accessed by any container in the pod.
+
+!!! tip ""
+    [API Reference](../../reference/cdk8s-plus-31/typescript.md#volume)
+
+## Create from a ConfigMap
+
+A very useful operation is to create a volume from a `ConfigMap`. Kubernetes will translate every key in the config map to a file,
+who's content is the value of the key.
+
+```typescript
+import * as kplus from 'cdk8s-plus-31';
+
+const configMap = kplus.ConfigMap.fromConfigMapName('redis-config');
+const configVolume = kplus.Volume.fromConfigMap(configMap);
+```
+
+## Create from an EmptyDir
+
+The easiest way to allocate some persistent storage to your container is to create a volume from an empty directory.
+This volume, as the name suggests, is initially empty, and can be written to by containers who mount it.
+The data in the volume is preserved throughout the lifecycle of the pod, but is deleted forever as soon as the pod itself is removed.
+
+```typescript
+import * as kplus from 'cdk8s-plus-31';
+
+const data = kplus.Volume.fromEmptyDir(configMap);
+
+const pod = new kplus.Pod(this, 'Pod');
+const redis = pod.addContainer({
+  image: 'redis'
+})
+
+// mount to the redis container.
+redis.mount('/var/lib/redis', data);
+```