Homelab 2 - Deno and cdk8s
This is part of a series on my homelab. You can view my code on GitHub. I’m also happy to answer any questions you might have.
cdk and cdk8s
If you’ve used CloudFormation, then you know how much it sucks. You use a weird dialect of YAML to define your AWS resources. Back in 2017 AWS introduced the cdk library. It allows you to generate your CloudFormation YAML using a real language like Go, Python, Java, or TypeScript.
This idea turned out to be execellent, so they did the same thing for Kubernetes with cdk8s. cdk8s seems to be abandonded, but it still works quite well. Since the TypeScript defitions are generated from Kubernetes’ resources (including third-party custom resource definitions!), the library should continue to work for quite a while longer.
Here’s a “hello world” program from cdk8s’ documentation:
import { import ConstructConstruct } from "constructs";
import { import AppApp, import ChartChart } from "cdk8s";
import { import KubeDeploymentKubeDeployment } from "./imports/k8s";
class class MyChartMyChart extends import ChartChart {
constructor(scope: Constructscope: import ConstructConstruct, ns: stringns: string, appLabel: stringappLabel: string) {
super(scope: Constructscope, ns: stringns);
// Define a Kubernetes Deployment
new import KubeDeploymentKubeDeployment(this, "my-deployment", {
spec: {
replicas: number;
selector: {
matchLabels: {
app: string;
};
};
template: {
metadata: {
labels: {
app: string;
};
};
spec: {
containers: {
name: string;
image: string;
ports: {
containerPort: number;
}[];
}[];
};
};
}
replicas: numberreplicas: 3,
selector: {
matchLabels: {
app: string;
};
}
matchLabels: {
app: string;
}
app: stringapp: appLabel: stringappLabel } },
template: {
metadata: {
labels: {
app: string;
};
};
spec: {
containers: {
name: string;
image: string;
ports: {
containerPort: number;
}[];
}[];
};
}
metadata: {
labels: {
app: string;
};
}
labels: {
app: string;
}
app: stringapp: appLabel: stringappLabel } },
spec: {
containers: {
name: string;
image: string;
ports: {
containerPort: number;
}[];
}[];
}
containers: {
name: string;
image: string;
ports: {
containerPort: number;
}[];
}[]
name: stringname: "app-container",
image: stringimage: "nginx:1.19.10",
ports: {
containerPort: number;
}[]
containerPort: numbercontainerPort: 80 }],
},
],
},
},
},
});
}
}
const const app: anyapp = new import AppApp();
new constructor MyChart(scope: Construct, ns: string, appLabel: string): MyChartMyChart(const app: anyapp, "getting-started", "my-app");
const app: anyapp.synth();The result of running this program is a Kubernetes YAML file that you can deploy using kubectl apply:
apiVersion: apps/v1
kind: Deployment
metadata:
name: getting-started-my-deployment-c85252a6
spec:
replicas: 3
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- image: nginx:1.19.10
name: app-container
ports:
- containerPort: 80Why is this useful? Static typing! cdk8s can inform guide you as you write your Kubernetes resources. For example, it can let you know what properties are valid when you’re creating a resource or let you know when you’ve specifiy an invalid property.
cdk8s has support for all of Kubernete’s resources. These definitions are generated by the cdk8s import command, which generates types for every Kubernetes resource on your server including CRDs (custom resource definitions). Here’s an example of a generated definition for 1Password, which I use to handle all of the secrets in my Kubernetes cluster:
export class class OnePasswordItemOnePasswordItem extends ApiObject {
public constructor(scope: Constructscope: type Construct = /*unresolved*/ anyConstruct, id: stringid: string, props: OnePasswordItemPropsprops: OnePasswordItemProps = {}) {
super(scope: Constructscope, id: stringid, {
...class OnePasswordItemOnePasswordItem.GVK,
...props: OnePasswordItemPropsprops,
});
}
}
export interface OnePasswordItemProps {
readonly OnePasswordItemProps.metadata?: anymetadata?: type ApiObjectMetadata = /*unresolved*/ anyApiObjectMetadata;
readonly OnePasswordItemProps.spec?: OnePasswordItemSpec | undefinedspec?: OnePasswordItemSpec;
readonly OnePasswordItemProps.type?: string | undefinedtype?: string;
}
export interface OnePasswordItemSpec {
readonly OnePasswordItemSpec.itemPath?: string | undefineditemPath?: string;
}Here’s how I use it to store my Tailscale key:
new OnePasswordItem(chart, "tailscale-operator-oauth-onepassword", {
spec: {
itemPath: string;
}
itemPath: stringitemPath: "vaults/v64ocnykdqju4ui6j6pua56xw4/items/mboftvs4fyptyqvg3anrfjy6vu",
},
metadata: {
name: string;
namespace: string;
}
name: stringname: "operator-oauth",
namespace: stringnamespace: "tailscale",
},
});Takeaway: cdk8s supports all Kubernetes resources, including third-party resources from 1Password, Tailscale, Traefik, etc.
Deno
Okay, so we have a way to write our all of our Kubernetes definitions in TypeScript. How do we actually compile our TypeScript to YAML?
The traditional way would be to use NodeJS, install TypeScript, compile the TypeScript to JavaScript, and then execute the result. This would work just fine!
However, I’m not a big fan of Node and would prefer to use a tool with TypeScript support built-in. I love the modern toolchains that languages like Rust and Go have. You can get something similar for TypeScript with Deno and Bun which are alternatives to NodeJS with native TypeScript support.
I’ve only really used Deno, so that’s what I’ll be showing in this post. I’m sure that Bun would work similarly well!
You’ll need to install Deno — this will include everything you need to compile and run a TypeScript program.
Deno has a few quirks — most of them are around imports. With Node you declare your dependencies in a package.json and your code will pull from node_modules. With Deno you declare your dependencies (and their versions) in your code and Deno will take care of downloading at runtime.
Because of this, the import format is a bit different. Rather than directly calling cdk8s import, we can use this script to create the correct imports for our generated Kubernetes types.
#!/usr/bin/env -S deno run --allow-run --allow-read --allow-write
// delete the imports directory
await Deno.remove("imports", { recursive: booleanrecursive: true });
// run "cdk8s import k8s --language=typescript"
let let command: anycommand = new Deno.Command("cdk8s", {
args: string[]args: ["import", "k8s", "--language=typescript"],
});
var console: Consoleconsole.Console.log(...data: any[]): voidThe **`console.log()`** static method outputs a message to the console.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)log(new var TextDecoder: new (label?: string, options?: TextDecoderOptions) => TextDecoderThe **`TextDecoder`** interface represents a decoder for a specific text encoding, such as `UTF-8`, `ISO-8859-2`, `KOI8-R`, `GBK`, etc.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/TextDecoder)TextDecoder().TextDecoder.decode(input?: AllowSharedBufferSource, options?: TextDecodeOptions): stringThe **`TextDecoder.decode()`** method returns a string containing text decoded from the buffer passed as a parameter.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/TextDecoder/decode)decode((await let command: anycommand.output()).stdout));
// run "kubectl get crds -o json | cdk8s import /dev/stdin --language=typescript"
let command: anycommand = new Deno.Command("bash", {
args: string[]args: [
"-c",
"kubectl get crds -o json | cdk8s import /dev/stdin --language=typescript",
],
});
var console: Consoleconsole.Console.log(...data: any[]): voidThe **`console.log()`** static method outputs a message to the console.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)log(new var TextDecoder: new (label?: string, options?: TextDecoderOptions) => TextDecoderThe **`TextDecoder`** interface represents a decoder for a specific text encoding, such as `UTF-8`, `ISO-8859-2`, `KOI8-R`, `GBK`, etc.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/TextDecoder)TextDecoder().TextDecoder.decode(input?: AllowSharedBufferSource, options?: TextDecodeOptions): stringThe **`TextDecoder.decode()`** method returns a string containing text decoded from the buffer passed as a parameter.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/TextDecoder/decode)decode((await let command: anycommand.output()).stdout));
const const files: anyfiles = Deno.readDir("imports");
// add "// deno-lint-ignore-file" to the top of each file in the imports directory
for await (const const file: anyfile of const files: anyfiles) {
if (const file: anyfile.isFile) {
const const filePath: stringfilePath = `imports/${const file: anyfile.name}`;
const const content: anycontent = await Deno.readTextFile(const filePath: stringfilePath);
await Deno.writeTextFile(
const filePath: stringfilePath,
`// deno-lint-ignore-file\n${const content: anycontent}`,
);
}
}
// look for "public toJson(): any {", change this to "public override toJson(): any {"
// fixes This member must have an 'override' modifier because it overrides a member in the base class 'ApiObject'.
for await (const const file: anyfile of const files: anyfiles) {
if (const file: anyfile.isFile) {
const const filePath: stringfilePath = `imports/${const file: anyfile.name}`;
let let content: anycontent = await Deno.readTextFile(const filePath: stringfilePath);
let content: anycontent = let content: anycontent.replaceAll(
"public toJson(): any {",
"public override toJson(): any {",
);
await Deno.writeTextFile(
const filePath: stringfilePath,
let content: anycontent,
);
}
}
// replace the npm import with the deno import
for await (const const file: anyfile of const files: anyfiles) {
if (const file: anyfile.isFile) {
const const filePath: stringfilePath = `imports/${const file: anyfile.name}`;
let let content: anycontent = await Deno.readTextFile(const filePath: stringfilePath);
let content: anycontent = let content: anycontent.replaceAll(
"from 'cdk8s'",
"from 'https://esm.sh/[email protected]'",
);
let content: anycontent = let content: anycontent.replaceAll(
"from 'constructs'",
"from 'https://esm.sh/[email protected]'",
);
await Deno.writeTextFile(
const filePath: stringfilePath,
let content: anycontent,
);
}
}
// run deno fmt
let command: anycommand = new Deno.Command("deno", {
args: string[]args: ["fmt", "imports"],
});
var console: Consoleconsole.Console.log(...data: any[]): voidThe **`console.log()`** static method outputs a message to the console.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)log(new var TextDecoder: new (label?: string, options?: TextDecoderOptions) => TextDecoderThe **`TextDecoder`** interface represents a decoder for a specific text encoding, such as `UTF-8`, `ISO-8859-2`, `KOI8-R`, `GBK`, etc.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/TextDecoder)TextDecoder().TextDecoder.decode(input?: AllowSharedBufferSource, options?: TextDecodeOptions): stringThe **`TextDecoder.decode()`** method returns a string containing text decoded from the buffer passed as a parameter.
[MDN Reference](https://developer.mozilla.org/docs/Web/API/TextDecoder/decode)decode((await let command: anycommand.output()).stdout));We can save this file and then run it with the deno command line, e.g. deno <file>.
Next, we’ll need to update our app’s imports. We can take the program we wrote up above and change the imports to use esm.sh.
import { import ConstructConstruct } from "https://esm.sh/[email protected]";
import { import AppApp, import ChartChart } from "https://esm.sh/[email protected]";
import { import KubeDeploymentKubeDeployment } from "./imports/k8s";Now, assuming our code is stored in app.ts, we can run deno run app.ts. This will compile our TypeScript code to Kubernetes YAML using Deno. Just like before, we can use kubectl apply to actually create these resources.
Conclusion
In the past two posts I’ve shown you how to create a Kubernetes cluster using k3s and use cdk8s + Deno to deploy resources to your cluster. In my next post I’ll cover automating deployments using ArgoCD.