• Menu

    NPM support

    Important
    		 this support is experimental for now, if validated we would envision to release the bundles on npm registry and therefore this documentation would be outdated.

    Features

    From the build, we generate .d.ts enabling you to get typescript build validation and completion in your preferred IDE to write script.

    How to use

    For now, the declaration files are only pushed to Maven central repository and not yet to npm registry. Therefore to set it up, you must download the files from your build. Here is how to do it:

    package.json
    {
    "devDependencies": { // (1)
        "typescript": "^4.7.4",
        "ts-node": "^10.9.1"
    },
    "scripts": { // (2)
        "postinstall": "node build/kubernetes-descriptors.install.mjs"
    }
}

    1. We import typescript to ensure we have the syntax validation and the completion in the editors,

    2. We execute after the installation - could be before - a script which will download and setup the kubernetes-descriptors dependency.

    kubernetes-descriptors.install.mjs will simply download the d.ts and package.json file in the right version from central:

    kubernetes-descriptors.install.mjs
    import { copyFileSync, mkdirSync } from 'fs';

// VARIABLES
const KUBERNETES_VERSION = process.env.KUBERNETES_VERSION || '1.24.3';
const KUBERNETES_DESCRIPTOR_VERSION = process.env.KUBERNETES_DESCRIPTOR_VERSION || '1.0-SNAPSHOT';
const REPOSITORY = process.env.MAVEN_CENTRAL || 'https://repo.maven.apache.org/maven2';
const TARGET = process.env.OUTPUT || 'node_modules/kubernetes-descriptors';

// START OF THE SCRIPT
const baseUrl = `${REPOSITORY}/io/yupiik/kubernetes/kubernetes-java-${KUBERNETES_VERSION}/${KUBERNETES_DESCRIPTOR_VERSION}/kubernetes-java-${KUBERNETES_VERSION}-${KUBERNETES_DESCRIPTOR_VERSION}-`;
const declarationTs = `${baseUrl}d.ts`;
const packageJson = `${baseUrl}package.json`;

async function download(url, target) {
    const response = await fetch(url);
    if (response.status != 200) {
        throw new Error(`Invalid download: HTTP ${response.status}`);
    }
    const out = fs.createWriteStream(target);
    await new Promise((resolve, reject) => {
        res.body.pipe(out);
        res.body.on('error', reject);
        fileStream.on('finish', resolve);
    });
}

mkdirSync(TARGET, { recursive: true });

const dTsName = declarationTs.substring(declarationTs.lastIndexOf('/') + 1);
download(declarationTs, `${TARGET}/${dTsName.substring(0, dTsName.length - KUBERNETES_DESCRIPTOR_VERSION.length - '--d.ts'.length)}.d.ts`);
download(packageJson, `${TARGET}/package.json`);

    Now just execute npm i and you will be set up.

    To start generating kubernetes descriptors, just create a script index.ts you will execute with npm run generate. To do it we first add this script in our package.json:

    package.json
    {
    "scripts": {
        "postinstall": "node build/kubernetes-descriptors.install.mjs",
        "generate": "npx ts-node index.ts" (1)
    },
    // ... as before
}

    1. The new command we add to generate the descriptors.

    And the script itself will import the model to modelize the descriptors and will serialize the model as JSON:

    index.ts
    import { writeFileSync, mkdirSync } from 'fs';
import { io } from 'kubernetes-descriptors'; // (1)
import v1 = io.yupiik.kubernetes.bindings.v1_9_8.v1; // (2)

const deployment = <v1.Deployment>{ // (3)
    apiVersion: 'v1',
    kind: 'Deployment',
    spec: {
        template: {
            metadata: {
                name: 'my-deployment',
            },
            spec: {
                containers: [
                    {
                        name: 'hello-world',
                        image: 'hello-world',
                    },
                ],
            },
        },
    },
};

// (4)
const target = 'dist/';
const bundlebeeDescriptors = `${target}/bundlebee/kubernetes`;
mkdirSync(bundlebeeDescriptors, { recursive: true });
writeFileSync(`${bundlebeeDescriptors}/deployment.json`, JSON.stringify(deployment, null, 2));

    1. Import the root namespace of the descriptors,

    2. Alias (to be shorter) the actual namespace we target (the version in general),

    3. Create a model matching the expected type (here Deployment), this is what gives us completion and validation,

    4. Just export the model writing the model (deployment) as JSON (thanks JSON.stringify) on the filesystem.

    Navigation