├── .eslintrc.json ├── .gitattributes ├── .github ├── ISSUE_TEMPLATE │ ├── bug.md │ ├── config.yml │ ├── feature-request.md │ └── rfc.md ├── semantic.yml └── workflows │ ├── auto-approve.yml │ ├── auto-queue.yml │ ├── build.yml │ ├── pull-request-lint.yml │ ├── security.yml │ ├── stale.yml │ ├── triage.yml │ ├── upgrade-compiler-dependencies.yml │ ├── upgrade-configuration.yml │ ├── upgrade-dev-dependencies.yml │ ├── upgrade-runtime-dependencies.yml │ └── website.yml ├── .gitignore ├── .npmignore ├── .projen ├── deps.json ├── files.json └── tasks.json ├── .projenrc.ts ├── ADOPTERS.md ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── DCO ├── LICENSE ├── OWNERS.md ├── README.md ├── ROADMAP.md ├── SECURITY.md ├── docs ├── .gitignore ├── .pages ├── LICENSE ├── README.md ├── assets │ ├── animation.gif │ ├── corevsplus.png │ ├── extra.css │ ├── favicon.png │ ├── logo.png │ ├── logos │ │ ├── cdk8s-vectors.ai │ │ ├── horizontal │ │ │ ├── cdk8s.horizontal.black.png │ │ │ ├── cdk8s.horizontal.black.svg │ │ │ ├── cdk8s.horizontal.color.png │ │ │ ├── cdk8s.horizontal.color.svg │ │ │ ├── cdk8s.horizontal.white.png │ │ │ └── cdk8s.horizontal.white.svg │ │ ├── icon │ │ │ ├── cdk8s.icon.black.png │ │ │ ├── cdk8s.icon.black.svg │ │ │ ├── cdk8s.icon.color.png │ │ │ ├── cdk8s.icon.color.svg │ │ │ ├── cdk8s.icon.white.png │ │ │ └── cdk8s.icon.white.svg │ │ └── stacked │ │ │ ├── cdk8s.stacked.black.png │ │ │ ├── cdk8s.stacked.black.svg │ │ │ ├── cdk8s.stacked.color.png │ │ │ ├── cdk8s.stacked.color.svg │ │ │ ├── cdk8s.stacked.white.png │ │ │ └── cdk8s.stacked.white.svg │ └── opengraph.jpg ├── basics │ ├── .pages │ ├── api-object.md │ ├── app.md │ ├── chart.md │ ├── constructs.md │ ├── deps.md │ ├── escape-hatches.md │ ├── helm.md │ ├── include.md │ ├── index.md │ └── testing.md ├── build.sh ├── cli │ ├── .pages │ ├── import.md │ ├── index.md │ ├── init.md │ ├── installation.md │ └── synth.md ├── ecosystem-interoperability.md ├── examples │ ├── .pages │ └── index.md ├── get-started │ ├── .pages │ ├── go.md │ ├── index.md │ ├── java.md │ ├── python.md │ └── typescript.md ├── index.md ├── landing-page-1900x1200.png ├── media.md ├── migrating-from-1.x.md ├── plus │ ├── .pages │ └── index.md ├── reference │ ├── .pages │ ├── cdk8s-plus-27 │ │ ├── .pages │ │ ├── go.md │ │ ├── java.md │ │ ├── python.md │ │ └── typescript.md │ ├── cdk8s-plus-28 │ │ ├── .pages │ │ └── go.md │ ├── cdk8s-plus-29 │ │ ├── .pages │ │ └── go.md │ ├── cdk8s-plus-30 │ │ ├── .pages │ │ └── go.md │ ├── cdk8s-plus-31 │ │ ├── .pages │ │ └── go.md │ ├── cdk8s-plus-32 │ │ ├── .pages │ │ └── go.md │ ├── cdk8s │ │ ├── .pages │ │ └── go.md │ └── index.md └── requirements.txt ├── examples ├── go │ ├── crd │ │ └── README.md │ ├── hello │ │ └── README.md │ ├── helm-bitnami │ │ └── README.md │ └── web-service │ │ └── README.md ├── java │ ├── crd │ │ └── README.md │ ├── hello │ │ └── README.md │ ├── helm-bitnami │ │ └── README.md │ └── web-service │ │ └── README.md ├── python │ ├── crd │ │ └── README.md │ ├── hello │ │ └── README.md │ ├── helm-bitnami │ │ └── README.md │ └── web-service │ │ └── README.md └── typescript │ ├── cdk8s-plus-elasticsearch-query │ └── README.md │ ├── cdk8s-plus-ingress │ └── README.md │ ├── crd │ └── README.md │ ├── hello │ └── README.md │ ├── helm-bitnami │ └── README.md │ ├── include-dashboard │ └── README.md │ ├── podinfo │ └── README.md │ ├── web-cache-db │ └── README.md │ └── web-service │ └── README.md ├── git-hooks ├── README.md ├── prepare-commit-msg └── setup.sh ├── kubernetes-schemas ├── v1.14.0 │ └── _definitions.json ├── v1.15.0 │ └── _definitions.json ├── v1.16.0 │ └── _definitions.json ├── v1.17.0 │ └── _definitions.json ├── v1.18.0 │ └── _definitions.json ├── v1.19.0 │ └── _definitions.json ├── v1.20.0 │ └── _definitions.json ├── v1.21.0 │ └── _definitions.json ├── v1.22.0 │ └── _definitions.json ├── v1.23.0 │ └── _definitions.json ├── v1.24.0 │ └── _definitions.json ├── v1.25.0 │ └── _definitions.json ├── v1.26.0 │ └── _definitions.json ├── v1.27.0 │ └── _definitions.json ├── v1.28.0 │ └── _definitions.json ├── v1.29.0 │ └── _definitions.json ├── v1.30.0 │ └── _definitions.json ├── v1.31.0 │ └── _definitions.json └── v1.32.0 │ └── _definitions.json ├── lerna.json ├── mkdocs.yml ├── package.json ├── research ├── README.md └── high-level-abstractions │ ├── README.md │ └── config-map-volume-in-pod │ └── README.md ├── rfc ├── 0000-template.md ├── 1216-resolve-cloud-tokens.md ├── 1216-stage-pyhsical-id.png ├── 1251-helm-synthesis.md ├── 1272-helm-import.md ├── images │ ├── build-time-validation-gate.png │ ├── deploy-time-validation-gate.png │ ├── dev-time-validation-gate.png │ └── lifecycle.png ├── manifest-validation.md └── sandbox-submission.md ├── src ├── latest-k8s-version.txt └── rotate-cdk8s-plus.ts ├── tools └── import-spec.sh ├── tsconfig.dev.json ├── tsconfig.json ├── website ├── .gitignore ├── .hugo_build.lock ├── LICENSE ├── README.md ├── archetypes │ └── default.md ├── build.sh ├── config.yaml ├── layouts │ ├── index.html │ └── sitemap.xml ├── static │ ├── CNAME │ ├── css │ │ ├── cdk8s.webflow.css │ │ ├── normalize.css │ │ └── webflow.css │ ├── images │ │ ├── 1.png │ │ ├── 1_1.png │ │ ├── 2.png │ │ ├── 2_1.png │ │ ├── 3.png │ │ ├── 3_1.png │ │ ├── 4.png │ │ ├── 5.png │ │ ├── aks.svg │ │ ├── animation.gif │ │ ├── asset-1902x.png │ │ ├── cncf-white.svg │ │ ├── csharp.png │ │ ├── eks.svg │ │ ├── favicon.png │ │ ├── git-small.png │ │ ├── git.png │ │ ├── gke.svg │ │ ├── go.png │ │ ├── ibm.svg │ │ ├── java.png │ │ ├── js.png │ │ ├── logo-white-p-500.png │ │ ├── logo-white-p-800.png │ │ ├── logo-white.png │ │ ├── logo.svg │ │ ├── main-p-500.png │ │ ├── main.png │ │ ├── opengraph.jpg │ │ ├── py.png │ │ ├── slack.png │ │ └── ts.png │ ├── js │ │ └── webflow.js │ ├── robots.txt │ └── sitemap-root.xml └── visuals │ └── vectors.ai └── yarn.lock /.eslintrc.json: -------------------------------------------------------------------------------- 1 | // ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | { 3 | "env": { 4 | "jest": true, 5 | "node": true 6 | }, 7 | "root": true, 8 | "plugins": [ 9 | "@typescript-eslint", 10 | "import", 11 | "@stylistic" 12 | ], 13 | "parser": "@typescript-eslint/parser", 14 | "parserOptions": { 15 | "ecmaVersion": 2018, 16 | "sourceType": "module", 17 | "project": "./tsconfig.dev.json" 18 | }, 19 | "extends": [ 20 | "plugin:import/typescript" 21 | ], 22 | "settings": { 23 | "import/parsers": { 24 | "@typescript-eslint/parser": [ 25 | ".ts", 26 | ".tsx" 27 | ] 28 | }, 29 | "import/resolver": { 30 | "node": {}, 31 | "typescript": { 32 | "project": "./tsconfig.dev.json", 33 | "alwaysTryTypes": true 34 | } 35 | } 36 | }, 37 | "ignorePatterns": [ 38 | "*.js", 39 | "*.d.ts", 40 | "node_modules/", 41 | "*.generated.ts", 42 | "coverage", 43 | "!.projenrc.ts", 44 | "!projenrc/**/*.ts" 45 | ], 46 | "rules": { 47 | "@stylistic/indent": [ 48 | "error", 49 | 2 50 | ], 51 | "@stylistic/quotes": [ 52 | "error", 53 | "single", 54 | { 55 | "avoidEscape": true 56 | } 57 | ], 58 | "@stylistic/comma-dangle": [ 59 | "error", 60 | "always-multiline" 61 | ], 62 | "@stylistic/comma-spacing": [ 63 | "error", 64 | { 65 | "before": false, 66 | "after": true 67 | } 68 | ], 69 | "@stylistic/no-multi-spaces": [ 70 | "error", 71 | { 72 | "ignoreEOLComments": false 73 | } 74 | ], 75 | "@stylistic/array-bracket-spacing": [ 76 | "error", 77 | "never" 78 | ], 79 | "@stylistic/array-bracket-newline": [ 80 | "error", 81 | "consistent" 82 | ], 83 | "@stylistic/object-curly-spacing": [ 84 | "error", 85 | "always" 86 | ], 87 | "@stylistic/object-curly-newline": [ 88 | "error", 89 | { 90 | "multiline": true, 91 | "consistent": true 92 | } 93 | ], 94 | "@stylistic/object-property-newline": [ 95 | "error", 96 | { 97 | "allowAllPropertiesOnSameLine": true 98 | } 99 | ], 100 | "@stylistic/keyword-spacing": [ 101 | "error" 102 | ], 103 | "@stylistic/brace-style": [ 104 | "error", 105 | "1tbs", 106 | { 107 | "allowSingleLine": true 108 | } 109 | ], 110 | "@stylistic/space-before-blocks": [ 111 | "error" 112 | ], 113 | "@stylistic/member-delimiter-style": [ 114 | "error" 115 | ], 116 | "@stylistic/semi": [ 117 | "error", 118 | "always" 119 | ], 120 | "@stylistic/max-len": [ 121 | "error", 122 | { 123 | "code": 150, 124 | "ignoreUrls": true, 125 | "ignoreStrings": true, 126 | "ignoreTemplateLiterals": true, 127 | "ignoreComments": true, 128 | "ignoreRegExpLiterals": true 129 | } 130 | ], 131 | "@stylistic/quote-props": [ 132 | "error", 133 | "consistent-as-needed" 134 | ], 135 | "@stylistic/key-spacing": [ 136 | "error" 137 | ], 138 | "@stylistic/no-multiple-empty-lines": [ 139 | "error" 140 | ], 141 | "@stylistic/no-trailing-spaces": [ 142 | "error" 143 | ], 144 | "curly": [ 145 | "error", 146 | "multi-line", 147 | "consistent" 148 | ], 149 | "@typescript-eslint/no-require-imports": "error", 150 | "import/no-extraneous-dependencies": [ 151 | "error", 152 | { 153 | "devDependencies": [ 154 | "**/test/**", 155 | "**/build-tools/**", 156 | ".projenrc.ts", 157 | "projenrc/**/*.ts" 158 | ], 159 | "optionalDependencies": false, 160 | "peerDependencies": true 161 | } 162 | ], 163 | "import/no-unresolved": [ 164 | "error" 165 | ], 166 | "import/order": [ 167 | "warn", 168 | { 169 | "groups": [ 170 | "builtin", 171 | "external" 172 | ], 173 | "alphabetize": { 174 | "order": "asc", 175 | "caseInsensitive": true 176 | } 177 | } 178 | ], 179 | "import/no-duplicates": [ 180 | "error" 181 | ], 182 | "no-shadow": [ 183 | "off" 184 | ], 185 | "@typescript-eslint/no-shadow": "error", 186 | "@typescript-eslint/no-floating-promises": "error", 187 | "no-return-await": [ 188 | "off" 189 | ], 190 | "@typescript-eslint/return-await": "error", 191 | "dot-notation": [ 192 | "error" 193 | ], 194 | "no-bitwise": [ 195 | "error" 196 | ], 197 | "@typescript-eslint/member-ordering": [ 198 | "error", 199 | { 200 | "default": [ 201 | "public-static-field", 202 | "public-static-method", 203 | "protected-static-field", 204 | "protected-static-method", 205 | "private-static-field", 206 | "private-static-method", 207 | "field", 208 | "constructor", 209 | "method" 210 | ] 211 | } 212 | ] 213 | }, 214 | "overrides": [ 215 | { 216 | "files": [ 217 | ".projenrc.ts" 218 | ], 219 | "rules": { 220 | "@typescript-eslint/no-require-imports": "off", 221 | "import/no-extraneous-dependencies": "off" 222 | } 223 | } 224 | ] 225 | } 226 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | # ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | 3 | * text=auto eol=lf 4 | *.snap linguist-generated 5 | /.eslintrc.json linguist-generated 6 | /.gitattributes linguist-generated 7 | /.github/ISSUE_TEMPLATE/bug.md linguist-generated 8 | /.github/ISSUE_TEMPLATE/config.yml linguist-generated 9 | /.github/ISSUE_TEMPLATE/feature-request.md linguist-generated 10 | /.github/workflows/auto-approve.yml linguist-generated 11 | /.github/workflows/auto-queue.yml linguist-generated 12 | /.github/workflows/build.yml linguist-generated 13 | /.github/workflows/pull-request-lint.yml linguist-generated 14 | /.github/workflows/security.yml linguist-generated 15 | /.github/workflows/stale.yml linguist-generated 16 | /.github/workflows/triage.yml linguist-generated 17 | /.github/workflows/upgrade-compiler-dependencies.yml linguist-generated 18 | /.github/workflows/upgrade-configuration.yml linguist-generated 19 | /.github/workflows/upgrade-dev-dependencies.yml linguist-generated 20 | /.github/workflows/upgrade-runtime-dependencies.yml linguist-generated 21 | /.github/workflows/website.yml linguist-generated 22 | /.gitignore linguist-generated 23 | /.npmignore linguist-generated 24 | /.projen/** linguist-generated 25 | /.projen/deps.json linguist-generated 26 | /.projen/files.json linguist-generated 27 | /.projen/tasks.json linguist-generated 28 | /CODE_OF_CONDUCT.md linguist-generated 29 | /DCO linguist-generated 30 | /git-hooks/prepare-commit-msg linguist-generated 31 | /git-hooks/README.md linguist-generated 32 | /git-hooks/setup.sh linguist-generated 33 | /LICENSE linguist-generated 34 | /package.json linguist-generated 35 | /SECURITY.md linguist-generated 36 | /tsconfig.dev.json linguist-generated 37 | /tsconfig.json linguist-generated 38 | /yarn.lock linguist-generated -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: "\U0001F41B Bug Report" 3 | about: Report a bug 4 | title: '' 5 | labels: bug, needs-triage 6 | assignees: '' 7 | 8 | --- 9 | 10 | 13 | 14 | ### Description of the bug: 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | ### Reproduction Steps: 23 | 24 | 25 | 26 | 27 | 28 | 29 | ### Error Log: 30 | 31 | 32 | 33 | 34 | 35 | ### Environment: 36 | 37 | 38 | - **Framework Version**: 39 | - **OS**: 40 | 41 | 42 | ### Other: 43 | 44 | 45 | 46 | 47 | 48 | --- 49 | 50 | This is :bug: Bug Report -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | # ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | 3 | blank_issues_enabled: false 4 | contact_links: 5 | - name: Slack Community Support @ cdk.dev 6 | url: https://cdk-dev.slack.com/archives/C0184GCBY4X 7 | about: Please ask and answer questions here. 8 | - name: Slack Community Support @ cncf.io 9 | url: https://cloud-native.slack.com/archives/C02KCDACGTT 10 | about: Please ask and answer questions here. 11 | - name: GitHub Community Support 12 | url: https://github.com/cdk8s-team/cdk8s/discussions 13 | about: Please ask and answer questions here. 14 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature-request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: "\U0001F680 Feature Request" 3 | about: Request a new feature 4 | title: '' 5 | labels: feature-request, needs-triage 6 | assignees: '' 7 | 8 | --- 9 | 10 | 13 | 14 | ### Description of the feature or enhancement: 15 | 16 | 17 | 18 | 19 | 20 | 21 | ### Use Case: 22 | 23 | 24 | 25 | 26 | 27 | 28 | ### Proposed Solution: 29 | 30 | 31 | 32 | 33 | 34 | 35 | ### Other: 36 | 40 | 41 | 42 | 43 | 44 | 45 | * [ ] :wave: I may be able to implement this feature request 46 | * [ ] :warning: This feature might incur a breaking change 47 | 48 | --- 49 | 50 | This is a :rocket: Feature Request -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/rfc.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: RFC 3 | about: Propose a significant change to the cdk8s toolchain 4 | title: RFC | describe your RFC 5 | labels: rfc/proposed 6 | assignees: '' 7 | 8 | --- 9 | 10 | ## Description 11 | 12 | Short description of the proposed feature. 13 | 14 | ## Roles 15 | 16 | | Role | User 17 | |---------------------|------------------------------ 18 | | Proposed by | @alias 19 | | Author(s) | @alias, @alias, @alias 20 | | API Bar Raiser | @alias 21 | | Stakeholders | @alias, @alias, @alias 22 | 23 | > See [RFC Process](https://github.com/cdk8s-team/cdk8s#rfc-process) for details 24 | 25 | ## Workflow 26 | 27 | - [x] Tracking issue created (label: `rfc/proposed`) 28 | - [ ] API bar raiser assigned (ping us at [#cdk8s](https://cdk-dev.slack.com/archives/C0184GCBY4X) if needed) 29 | - [ ] Kick off meeting 30 | - [ ] RFC pull request submitted (label: `rfc/review`) 31 | - [ ] Community reach out (via Slack and/or Twitter) 32 | - [ ] API signed-off (label `rfc/api-approved` applied to pull request) 33 | - [ ] Final comments period (label: `rfc/final-comments-period`) 34 | - [ ] Approved and merged (label: `rfc/approved`) 35 | - [ ] Execution plan submitted (label: `rfc/planning`) 36 | - [ ] Plan approved and merged (label: `rfc/implementing`) 37 | - [ ] Implementation complete (label: `rfc/done`) 38 | 39 | --- 40 | 41 | > Author is responsible to progress the RFC according to this checklist, and 42 | apply the relevant labels to this issue so that the RFC table in README gets 43 | updated. 44 | -------------------------------------------------------------------------------- /.github/semantic.yml: -------------------------------------------------------------------------------- 1 | # only validate PR title because it will be used as the merge commit title 2 | titleOnly: true 3 | 4 | # only allow these scopes 5 | scopes: 6 | - lib 7 | - cli 8 | - plus-17 9 | - examples 10 | - readme 11 | - docs 12 | - website 13 | - release 14 | - deps 15 | 16 | # only allow these types 17 | types: 18 | - feat 19 | - fix 20 | - chore 21 | - refactor 22 | - revert 23 | -------------------------------------------------------------------------------- /.github/workflows/auto-approve.yml: -------------------------------------------------------------------------------- 1 | # ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | 3 | name: auto-approve 4 | on: 5 | pull_request_target: 6 | types: 7 | - labeled 8 | - opened 9 | - synchronize 10 | - reopened 11 | - ready_for_review 12 | jobs: 13 | approve: 14 | runs-on: ubuntu-latest 15 | permissions: 16 | pull-requests: write 17 | if: contains(github.event.pull_request.labels.*.name, 'auto-approve') && (github.event.pull_request.user.login == 'cdk8s-automation') 18 | steps: 19 | - uses: hmarr/auto-approve-action@v2.2.1 20 | with: 21 | github-token: ${{ secrets.GITHUB_TOKEN }} 22 | -------------------------------------------------------------------------------- /.github/workflows/auto-queue.yml: -------------------------------------------------------------------------------- 1 | # ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | 3 | name: auto-queue 4 | on: 5 | pull_request_target: 6 | types: 7 | - opened 8 | - reopened 9 | - ready_for_review 10 | jobs: 11 | enableAutoQueue: 12 | name: "Set AutoQueue on PR #${{ github.event.number }}" 13 | runs-on: ubuntu-latest 14 | permissions: 15 | pull-requests: write 16 | contents: write 17 | steps: 18 | - uses: peter-evans/enable-pull-request-automerge@v3 19 | with: 20 | token: ${{ secrets.PROJEN_GITHUB_TOKEN }} 21 | pull-request-number: ${{ github.event.number }} 22 | merge-method: squash 23 | -------------------------------------------------------------------------------- /.github/workflows/build.yml: -------------------------------------------------------------------------------- 1 | # ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | 3 | name: build 4 | on: 5 | pull_request: {} 6 | workflow_dispatch: {} 7 | merge_group: {} 8 | jobs: 9 | build: 10 | runs-on: ubuntu-latest 11 | permissions: 12 | contents: write 13 | outputs: 14 | self_mutation_happened: ${{ steps.self_mutation.outputs.self_mutation_happened }} 15 | env: 16 | CI: "true" 17 | steps: 18 | - name: Checkout 19 | uses: actions/checkout@v4 20 | with: 21 | ref: ${{ github.event.pull_request.head.ref }} 22 | repository: ${{ github.event.pull_request.head.repo.full_name }} 23 | - name: Setup Node.js 24 | uses: actions/setup-node@v4 25 | with: 26 | node-version: lts/* 27 | - name: Install dependencies 28 | run: yarn install --check-files 29 | - name: build 30 | run: npx projen build 31 | - name: Find mutations 32 | id: self_mutation 33 | run: |- 34 | git add . 35 | git diff --staged --patch --exit-code > repo.patch || echo "self_mutation_happened=true" >> $GITHUB_OUTPUT 36 | working-directory: ./ 37 | - name: Upload patch 38 | if: steps.self_mutation.outputs.self_mutation_happened 39 | uses: actions/upload-artifact@v4.4.0 40 | with: 41 | name: repo.patch 42 | path: repo.patch 43 | overwrite: true 44 | - name: Fail build on mutation 45 | if: steps.self_mutation.outputs.self_mutation_happened 46 | run: |- 47 | echo "::error::Files were changed during build (see build log). If this was triggered from a fork, you will need to update your branch." 48 | cat repo.patch 49 | exit 1 50 | self-mutation: 51 | needs: build 52 | runs-on: ubuntu-latest 53 | permissions: 54 | contents: write 55 | if: always() && needs.build.outputs.self_mutation_happened && !(github.event.pull_request.head.repo.full_name != github.repository) 56 | steps: 57 | - name: Checkout 58 | uses: actions/checkout@v4 59 | with: 60 | token: ${{ secrets.PROJEN_GITHUB_TOKEN }} 61 | ref: ${{ github.event.pull_request.head.ref }} 62 | repository: ${{ github.event.pull_request.head.repo.full_name }} 63 | - name: Download patch 64 | uses: actions/download-artifact@v4 65 | with: 66 | name: repo.patch 67 | path: ${{ runner.temp }} 68 | - name: Apply patch 69 | run: '[ -s ${{ runner.temp }}/repo.patch ] && git apply ${{ runner.temp }}/repo.patch || echo "Empty patch. Skipping."' 70 | - name: Set git identity 71 | run: |- 72 | git config user.name "github-actions" 73 | git config user.email "github-actions@github.com" 74 | - name: Push changes 75 | env: 76 | PULL_REQUEST_REF: ${{ github.event.pull_request.head.ref }} 77 | run: |- 78 | git add . 79 | git commit -s -m "chore: self mutation" 80 | git push origin HEAD:$PULL_REQUEST_REF 81 | -------------------------------------------------------------------------------- /.github/workflows/pull-request-lint.yml: -------------------------------------------------------------------------------- 1 | # ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | 3 | name: pull-request-lint 4 | on: 5 | pull_request_target: 6 | types: 7 | - labeled 8 | - opened 9 | - synchronize 10 | - reopened 11 | - ready_for_review 12 | - edited 13 | merge_group: {} 14 | jobs: 15 | validate: 16 | name: Validate PR title 17 | runs-on: ubuntu-latest 18 | permissions: 19 | pull-requests: write 20 | if: (github.event_name == 'pull_request' || github.event_name == 'pull_request_target') 21 | steps: 22 | - uses: amannn/action-semantic-pull-request@v5.4.0 23 | env: 24 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 25 | with: 26 | types: |- 27 | feat 28 | fix 29 | chore 30 | requireScope: false 31 | -------------------------------------------------------------------------------- /.github/workflows/security.yml: -------------------------------------------------------------------------------- 1 | # ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | 3 | name: security 4 | on: 5 | schedule: 6 | - cron: 0 0 * * * 7 | workflow_dispatch: {} 8 | jobs: 9 | scan: 10 | runs-on: ubuntu-latest 11 | permissions: 12 | security-events: read 13 | issues: write 14 | steps: 15 | - name: scan 16 | uses: cdk8s-team/cdk8s-dependabot-security-alerts@main 17 | env: 18 | GITHUB_TOKEN: ${{ secrets.PROJEN_GITHUB_TOKEN }} 19 | REPO_ROOT: ${{ github.workspace }} 20 | REPO_NAME: ${{ github.repository }} 21 | OWNER_NAME: ${{ github.repository_owner }} 22 | -------------------------------------------------------------------------------- /.github/workflows/stale.yml: -------------------------------------------------------------------------------- 1 | # ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | 3 | name: stale 4 | on: 5 | workflow_dispatch: {} 6 | schedule: 7 | - cron: 0 */4 * * * 8 | jobs: 9 | scan: 10 | runs-on: ubuntu-latest 11 | permissions: 12 | issues: write 13 | pull-requests: write 14 | contents: read 15 | steps: 16 | - uses: aws-actions/stale-issue-cleanup@v6 17 | with: 18 | ancient-issue-message: This issue has not received any attention in 1 year and will be closed soon. If you want to keep it open, please leave a comment below @mentioning a maintainer. 19 | stale-issue-message: This issue has not received a response in a while and will be closed soon. If you want to keep it open, please leave a comment below @mentioning a maintainer. 20 | stale-pr-message: This PR has not received a response in a while and will be closed soon. If you want to keep it open, please leave a comment below @mentioning a maintainer. 21 | stale-issue-label: closing-soon 22 | exempt-issue-labels: no-autoclose 23 | stale-pr-label: closing-soon 24 | exempt-pr-labels: no-autoclose 25 | response-requested-label: response-requested 26 | closed-for-staleness-label: closed-for-staleness 27 | days-before-stale: 30 28 | days-before-close: 7 29 | days-before-ancient: 365 30 | minimum-upvotes-to-exempt: 10 31 | repo-token: ${{ secrets.GITHUB_TOKEN }} 32 | loglevel: DEBUG 33 | dry-run: false 34 | -------------------------------------------------------------------------------- /.github/workflows/triage.yml: -------------------------------------------------------------------------------- 1 | # ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | 3 | name: triage 4 | on: 5 | issues: 6 | types: 7 | - opened 8 | pull_request: 9 | types: 10 | - opened 11 | jobs: 12 | assign-to-project: 13 | runs-on: ubuntu-latest 14 | permissions: 15 | issues: write 16 | pull-requests: write 17 | if: (github.repository == 'cdk8s-team/cdk8s') && (github.event.issue || (github.event.pull_request.user.login != 'cdk8s-automation' && github.event.pull_request.head.repo.full_name == github.repository)) 18 | steps: 19 | - uses: actions/add-to-project@v0.4.0 20 | with: 21 | project-url: https://github.com/orgs/cdk8s-team/projects/12 22 | github-token: ${{ secrets.PROJEN_GITHUB_TOKEN }} 23 | -------------------------------------------------------------------------------- /.github/workflows/upgrade-compiler-dependencies.yml: -------------------------------------------------------------------------------- 1 | # ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | 3 | name: upgrade-compiler-dependencies 4 | on: 5 | workflow_dispatch: {} 6 | schedule: 7 | - cron: 0 12 * * * 8 | jobs: 9 | upgrade: 10 | name: Upgrade 11 | runs-on: ubuntu-latest 12 | permissions: 13 | contents: read 14 | outputs: 15 | patch_created: ${{ steps.create_patch.outputs.patch_created }} 16 | steps: 17 | - name: Checkout 18 | uses: actions/checkout@v4 19 | - name: Setup Node.js 20 | uses: actions/setup-node@v4 21 | with: 22 | node-version: lts/* 23 | - name: Install dependencies 24 | run: yarn install --check-files --frozen-lockfile 25 | - name: Upgrade dependencies 26 | run: npx projen upgrade-compiler-dependencies 27 | - name: Find mutations 28 | id: create_patch 29 | run: |- 30 | git add . 31 | git diff --staged --patch --exit-code > repo.patch || echo "patch_created=true" >> $GITHUB_OUTPUT 32 | working-directory: ./ 33 | - name: Upload patch 34 | if: steps.create_patch.outputs.patch_created 35 | uses: actions/upload-artifact@v4.4.0 36 | with: 37 | name: repo.patch 38 | path: repo.patch 39 | overwrite: true 40 | pr: 41 | name: Create Pull Request 42 | needs: upgrade 43 | runs-on: ubuntu-latest 44 | permissions: 45 | contents: read 46 | if: ${{ needs.upgrade.outputs.patch_created }} 47 | steps: 48 | - name: Checkout 49 | uses: actions/checkout@v4 50 | - name: Download patch 51 | uses: actions/download-artifact@v4 52 | with: 53 | name: repo.patch 54 | path: ${{ runner.temp }} 55 | - name: Apply patch 56 | run: '[ -s ${{ runner.temp }}/repo.patch ] && git apply ${{ runner.temp }}/repo.patch || echo "Empty patch. Skipping."' 57 | - name: Set git identity 58 | run: |- 59 | git config user.name "github-actions" 60 | git config user.email "github-actions@github.com" 61 | - name: Create Pull Request 62 | id: create-pr 63 | uses: peter-evans/create-pull-request@v6 64 | with: 65 | token: ${{ secrets.PROJEN_GITHUB_TOKEN }} 66 | commit-message: |- 67 | chore(deps): upgrade compiler dependencies 68 | 69 | Upgrades project dependencies. See details in [workflow run]. 70 | 71 | [Workflow Run]: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} 72 | 73 | ------ 74 | 75 | *Automatically created by projen via the "upgrade-compiler-dependencies" workflow* 76 | branch: github-actions/upgrade-compiler-dependencies 77 | title: "chore(deps): upgrade compiler dependencies" 78 | labels: auto-approve 79 | body: |- 80 | Upgrades project dependencies. See details in [workflow run]. 81 | 82 | [Workflow Run]: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} 83 | 84 | ------ 85 | 86 | *Automatically created by projen via the "upgrade-compiler-dependencies" workflow* 87 | author: github-actions 88 | committer: github-actions 89 | signoff: true 90 | -------------------------------------------------------------------------------- /.github/workflows/upgrade-configuration.yml: -------------------------------------------------------------------------------- 1 | # ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | 3 | name: upgrade-configuration 4 | on: 5 | workflow_dispatch: {} 6 | schedule: 7 | - cron: 0 15 * * * 8 | jobs: 9 | upgrade: 10 | name: Upgrade 11 | runs-on: ubuntu-latest 12 | permissions: 13 | contents: read 14 | outputs: 15 | patch_created: ${{ steps.create_patch.outputs.patch_created }} 16 | steps: 17 | - name: Checkout 18 | uses: actions/checkout@v4 19 | - name: Setup Node.js 20 | uses: actions/setup-node@v4 21 | with: 22 | node-version: lts/* 23 | - name: Install dependencies 24 | run: yarn install --check-files --frozen-lockfile 25 | - name: Upgrade dependencies 26 | run: npx projen upgrade-configuration 27 | - name: Find mutations 28 | id: create_patch 29 | run: |- 30 | git add . 31 | git diff --staged --patch --exit-code > repo.patch || echo "patch_created=true" >> $GITHUB_OUTPUT 32 | working-directory: ./ 33 | - name: Upload patch 34 | if: steps.create_patch.outputs.patch_created 35 | uses: actions/upload-artifact@v4.4.0 36 | with: 37 | name: repo.patch 38 | path: repo.patch 39 | overwrite: true 40 | pr: 41 | name: Create Pull Request 42 | needs: upgrade 43 | runs-on: ubuntu-latest 44 | permissions: 45 | contents: read 46 | if: ${{ needs.upgrade.outputs.patch_created }} 47 | steps: 48 | - name: Checkout 49 | uses: actions/checkout@v4 50 | - name: Download patch 51 | uses: actions/download-artifact@v4 52 | with: 53 | name: repo.patch 54 | path: ${{ runner.temp }} 55 | - name: Apply patch 56 | run: '[ -s ${{ runner.temp }}/repo.patch ] && git apply ${{ runner.temp }}/repo.patch || echo "Empty patch. Skipping."' 57 | - name: Set git identity 58 | run: |- 59 | git config user.name "github-actions" 60 | git config user.email "github-actions@github.com" 61 | - name: Create Pull Request 62 | id: create-pr 63 | uses: peter-evans/create-pull-request@v6 64 | with: 65 | token: ${{ secrets.PROJEN_GITHUB_TOKEN }} 66 | commit-message: |- 67 | chore(deps): upgrade configuration 68 | 69 | Upgrades project dependencies. See details in [workflow run]. 70 | 71 | [Workflow Run]: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} 72 | 73 | ------ 74 | 75 | *Automatically created by projen via the "upgrade-configuration" workflow* 76 | branch: github-actions/upgrade-configuration 77 | title: "chore(deps): upgrade configuration" 78 | labels: auto-approve 79 | body: |- 80 | Upgrades project dependencies. See details in [workflow run]. 81 | 82 | [Workflow Run]: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} 83 | 84 | ------ 85 | 86 | *Automatically created by projen via the "upgrade-configuration" workflow* 87 | author: github-actions 88 | committer: github-actions 89 | signoff: true 90 | -------------------------------------------------------------------------------- /.github/workflows/upgrade-dev-dependencies.yml: -------------------------------------------------------------------------------- 1 | # ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | 3 | name: upgrade-dev-dependencies 4 | on: 5 | workflow_dispatch: {} 6 | schedule: 7 | - cron: 0 9 * * * 8 | jobs: 9 | upgrade: 10 | name: Upgrade 11 | runs-on: ubuntu-latest 12 | permissions: 13 | contents: read 14 | outputs: 15 | patch_created: ${{ steps.create_patch.outputs.patch_created }} 16 | steps: 17 | - name: Checkout 18 | uses: actions/checkout@v4 19 | - name: Setup Node.js 20 | uses: actions/setup-node@v4 21 | with: 22 | node-version: lts/* 23 | - name: Install dependencies 24 | run: yarn install --check-files --frozen-lockfile 25 | - name: Upgrade dependencies 26 | run: npx projen upgrade-dev-dependencies 27 | - name: Find mutations 28 | id: create_patch 29 | run: |- 30 | git add . 31 | git diff --staged --patch --exit-code > repo.patch || echo "patch_created=true" >> $GITHUB_OUTPUT 32 | working-directory: ./ 33 | - name: Upload patch 34 | if: steps.create_patch.outputs.patch_created 35 | uses: actions/upload-artifact@v4.4.0 36 | with: 37 | name: repo.patch 38 | path: repo.patch 39 | overwrite: true 40 | pr: 41 | name: Create Pull Request 42 | needs: upgrade 43 | runs-on: ubuntu-latest 44 | permissions: 45 | contents: read 46 | if: ${{ needs.upgrade.outputs.patch_created }} 47 | steps: 48 | - name: Checkout 49 | uses: actions/checkout@v4 50 | - name: Download patch 51 | uses: actions/download-artifact@v4 52 | with: 53 | name: repo.patch 54 | path: ${{ runner.temp }} 55 | - name: Apply patch 56 | run: '[ -s ${{ runner.temp }}/repo.patch ] && git apply ${{ runner.temp }}/repo.patch || echo "Empty patch. Skipping."' 57 | - name: Set git identity 58 | run: |- 59 | git config user.name "github-actions" 60 | git config user.email "github-actions@github.com" 61 | - name: Create Pull Request 62 | id: create-pr 63 | uses: peter-evans/create-pull-request@v6 64 | with: 65 | token: ${{ secrets.PROJEN_GITHUB_TOKEN }} 66 | commit-message: |- 67 | chore(deps): upgrade dev dependencies 68 | 69 | Upgrades project dependencies. See details in [workflow run]. 70 | 71 | [Workflow Run]: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} 72 | 73 | ------ 74 | 75 | *Automatically created by projen via the "upgrade-dev-dependencies" workflow* 76 | branch: github-actions/upgrade-dev-dependencies 77 | title: "chore(deps): upgrade dev dependencies" 78 | labels: auto-approve 79 | body: |- 80 | Upgrades project dependencies. See details in [workflow run]. 81 | 82 | [Workflow Run]: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} 83 | 84 | ------ 85 | 86 | *Automatically created by projen via the "upgrade-dev-dependencies" workflow* 87 | author: github-actions 88 | committer: github-actions 89 | signoff: true 90 | -------------------------------------------------------------------------------- /.github/workflows/upgrade-runtime-dependencies.yml: -------------------------------------------------------------------------------- 1 | # ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | 3 | name: upgrade-runtime-dependencies 4 | on: 5 | workflow_dispatch: {} 6 | schedule: 7 | - cron: 0 6 * * * 8 | jobs: 9 | upgrade: 10 | name: Upgrade 11 | runs-on: ubuntu-latest 12 | permissions: 13 | contents: read 14 | outputs: 15 | patch_created: ${{ steps.create_patch.outputs.patch_created }} 16 | steps: 17 | - name: Checkout 18 | uses: actions/checkout@v4 19 | - name: Setup Node.js 20 | uses: actions/setup-node@v4 21 | with: 22 | node-version: lts/* 23 | - name: Install dependencies 24 | run: yarn install --check-files --frozen-lockfile 25 | - name: Upgrade dependencies 26 | run: npx projen upgrade-runtime-dependencies 27 | - name: Find mutations 28 | id: create_patch 29 | run: |- 30 | git add . 31 | git diff --staged --patch --exit-code > repo.patch || echo "patch_created=true" >> $GITHUB_OUTPUT 32 | working-directory: ./ 33 | - name: Upload patch 34 | if: steps.create_patch.outputs.patch_created 35 | uses: actions/upload-artifact@v4.4.0 36 | with: 37 | name: repo.patch 38 | path: repo.patch 39 | overwrite: true 40 | pr: 41 | name: Create Pull Request 42 | needs: upgrade 43 | runs-on: ubuntu-latest 44 | permissions: 45 | contents: read 46 | if: ${{ needs.upgrade.outputs.patch_created }} 47 | steps: 48 | - name: Checkout 49 | uses: actions/checkout@v4 50 | - name: Download patch 51 | uses: actions/download-artifact@v4 52 | with: 53 | name: repo.patch 54 | path: ${{ runner.temp }} 55 | - name: Apply patch 56 | run: '[ -s ${{ runner.temp }}/repo.patch ] && git apply ${{ runner.temp }}/repo.patch || echo "Empty patch. Skipping."' 57 | - name: Set git identity 58 | run: |- 59 | git config user.name "github-actions" 60 | git config user.email "github-actions@github.com" 61 | - name: Create Pull Request 62 | id: create-pr 63 | uses: peter-evans/create-pull-request@v6 64 | with: 65 | token: ${{ secrets.PROJEN_GITHUB_TOKEN }} 66 | commit-message: |- 67 | chore(deps): upgrade runtime dependencies 68 | 69 | Upgrades project dependencies. See details in [workflow run]. 70 | 71 | [Workflow Run]: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} 72 | 73 | ------ 74 | 75 | *Automatically created by projen via the "upgrade-runtime-dependencies" workflow* 76 | branch: github-actions/upgrade-runtime-dependencies 77 | title: "chore(deps): upgrade runtime dependencies" 78 | labels: auto-approve 79 | body: |- 80 | Upgrades project dependencies. See details in [workflow run]. 81 | 82 | [Workflow Run]: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} 83 | 84 | ------ 85 | 86 | *Automatically created by projen via the "upgrade-runtime-dependencies" workflow* 87 | author: github-actions 88 | committer: github-actions 89 | signoff: true 90 | -------------------------------------------------------------------------------- /.github/workflows/website.yml: -------------------------------------------------------------------------------- 1 | # ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | 3 | name: website 4 | on: 5 | push: 6 | branches: 7 | - master 8 | jobs: 9 | deploy: 10 | runs-on: ubuntu-latest 11 | permissions: 12 | contents: write 13 | steps: 14 | - name: Checkout sources 15 | uses: actions/checkout@v2 16 | - name: Setup Node.js 17 | uses: actions/setup-node@v2 18 | - name: Setup Hugo 19 | uses: peaceiris/actions-hugo@v2 20 | with: 21 | hugo-version: 0.68.3 22 | extended: true 23 | - name: Setup Python 24 | uses: actions/setup-python@v2 25 | with: 26 | python-version: 3.x 27 | architecture: x64 28 | - name: Install dependencies 29 | run: yarn install --frozen-lockfile 30 | - name: Build Website 31 | run: |- 32 | cd website 33 | ./build.sh 34 | - name: Build Docs Site 35 | run: ./docs/build.sh website/public/docs 36 | - name: Deploy 37 | uses: peaceiris/actions-gh-pages@v3 38 | with: 39 | github_token: ${{ secrets.GITHUB_TOKEN }} 40 | publish_dir: ./website/public 41 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | !/.gitattributes 3 | !/.projen/tasks.json 4 | !/.projen/deps.json 5 | !/.projen/files.json 6 | !/.github/workflows/auto-queue.yml 7 | !/.github/workflows/pull-request-lint.yml 8 | !/.github/workflows/auto-approve.yml 9 | !/package.json 10 | !/LICENSE 11 | !/.npmignore 12 | logs 13 | *.log 14 | npm-debug.log* 15 | yarn-debug.log* 16 | yarn-error.log* 17 | lerna-debug.log* 18 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json 19 | pids 20 | *.pid 21 | *.seed 22 | *.pid.lock 23 | lib-cov 24 | coverage 25 | *.lcov 26 | .nyc_output 27 | build/Release 28 | node_modules/ 29 | jspm_packages/ 30 | *.tsbuildinfo 31 | .eslintcache 32 | *.tgz 33 | .yarn-integrity 34 | .cache 35 | /test-reports/ 36 | junit.xml 37 | /coverage/ 38 | !/.github/workflows/build.yml 39 | !/.github/workflows/upgrade-runtime-dependencies.yml 40 | !/test/ 41 | !/tsconfig.json 42 | !/tsconfig.dev.json 43 | !/src/ 44 | /lib 45 | /dist/ 46 | !/.eslintrc.json 47 | !/CODE_OF_CONDUCT.md 48 | !/DCO 49 | !/git-hooks/prepare-commit-msg 50 | !/git-hooks/README.md 51 | !/git-hooks/setup.sh 52 | !/.github/ISSUE_TEMPLATE/bug.md 53 | !/.github/ISSUE_TEMPLATE/feature-request.md 54 | !/.github/ISSUE_TEMPLATE/config.yml 55 | !/SECURITY.md 56 | !/.github/workflows/security.yml 57 | !/.github/workflows/triage.yml 58 | !/.github/workflows/stale.yml 59 | !/.github/workflows/upgrade-configuration.yml 60 | !/.github/workflows/upgrade-dev-dependencies.yml 61 | !/.github/workflows/upgrade-compiler-dependencies.yml 62 | .vscode/ 63 | *.js 64 | *.d.ts 65 | dist/ 66 | !/.github/workflows/website.yml 67 | /docs/reference/cdk8s/java.md 68 | /docs/reference/cdk8s/typescript.md 69 | /docs/reference/cdk8s/python.md 70 | /docs/reference/cdk8s-plus-32/java.md 71 | /docs/reference/cdk8s-plus-32/typescript.md 72 | /docs/reference/cdk8s-plus-32/python.md 73 | /docs/reference/cdk8s-plus-31/java.md 74 | /docs/reference/cdk8s-plus-31/typescript.md 75 | /docs/reference/cdk8s-plus-31/python.md 76 | /docs/reference/cdk8s-plus-30/java.md 77 | /docs/reference/cdk8s-plus-30/typescript.md 78 | /docs/reference/cdk8s-plus-30/python.md 79 | !/.projenrc.ts 80 | -------------------------------------------------------------------------------- /.npmignore: -------------------------------------------------------------------------------- 1 | # ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | /.projen/ 3 | /test-reports/ 4 | junit.xml 5 | /coverage/ 6 | permissions-backup.acl 7 | /test/ 8 | /tsconfig.dev.json 9 | /src/ 10 | !/lib/ 11 | !/lib/**/*.js 12 | !/lib/**/*.d.ts 13 | dist 14 | /tsconfig.json 15 | /.github/ 16 | /.vscode/ 17 | /.idea/ 18 | /.projenrc.js 19 | tsconfig.tsbuildinfo 20 | /.eslintrc.json 21 | /.gitattributes 22 | /.projenrc.ts 23 | /projenrc 24 | -------------------------------------------------------------------------------- /.projen/deps.json: -------------------------------------------------------------------------------- 1 | { 2 | "dependencies": [ 3 | { 4 | "name": "@cdk8s/projen-common", 5 | "type": "build" 6 | }, 7 | { 8 | "name": "@stylistic/eslint-plugin", 9 | "version": "^2", 10 | "type": "build" 11 | }, 12 | { 13 | "name": "@types/jest", 14 | "type": "build" 15 | }, 16 | { 17 | "name": "@types/node", 18 | "version": "16.18.78", 19 | "type": "build" 20 | }, 21 | { 22 | "name": "@typescript-eslint/eslint-plugin", 23 | "version": "^8", 24 | "type": "build" 25 | }, 26 | { 27 | "name": "@typescript-eslint/parser", 28 | "version": "^8", 29 | "type": "build" 30 | }, 31 | { 32 | "name": "cdk8s", 33 | "type": "build" 34 | }, 35 | { 36 | "name": "cdk8s-cli", 37 | "type": "build" 38 | }, 39 | { 40 | "name": "cdk8s-plus-30", 41 | "type": "build" 42 | }, 43 | { 44 | "name": "cdk8s-plus-31", 45 | "type": "build" 46 | }, 47 | { 48 | "name": "cdk8s-plus-32", 49 | "type": "build" 50 | }, 51 | { 52 | "name": "constructs", 53 | "version": "^10.0.0", 54 | "type": "build" 55 | }, 56 | { 57 | "name": "eslint-import-resolver-typescript", 58 | "type": "build" 59 | }, 60 | { 61 | "name": "eslint-plugin-import", 62 | "type": "build" 63 | }, 64 | { 65 | "name": "eslint", 66 | "version": "^9", 67 | "type": "build" 68 | }, 69 | { 70 | "name": "jest", 71 | "type": "build" 72 | }, 73 | { 74 | "name": "jest-junit", 75 | "version": "^16", 76 | "type": "build" 77 | }, 78 | { 79 | "name": "lerna", 80 | "type": "build" 81 | }, 82 | { 83 | "name": "projen", 84 | "type": "build" 85 | }, 86 | { 87 | "name": "semver", 88 | "type": "build" 89 | }, 90 | { 91 | "name": "ts-jest", 92 | "type": "build" 93 | }, 94 | { 95 | "name": "ts-node", 96 | "type": "build" 97 | }, 98 | { 99 | "name": "typescript", 100 | "type": "build" 101 | }, 102 | { 103 | "name": "@types/responselike", 104 | "version": "1.0.0", 105 | "type": "override" 106 | }, 107 | { 108 | "name": "got", 109 | "version": "12.3.1", 110 | "type": "override" 111 | } 112 | ], 113 | "//": "~~ Generated by projen. To modify, edit .projenrc.ts and run \"npx projen\"." 114 | } 115 | -------------------------------------------------------------------------------- /.projen/files.json: -------------------------------------------------------------------------------- 1 | { 2 | "files": [ 3 | ".eslintrc.json", 4 | ".gitattributes", 5 | ".github/ISSUE_TEMPLATE/bug.md", 6 | ".github/ISSUE_TEMPLATE/config.yml", 7 | ".github/ISSUE_TEMPLATE/feature-request.md", 8 | ".github/workflows/auto-approve.yml", 9 | ".github/workflows/auto-queue.yml", 10 | ".github/workflows/build.yml", 11 | ".github/workflows/pull-request-lint.yml", 12 | ".github/workflows/security.yml", 13 | ".github/workflows/stale.yml", 14 | ".github/workflows/triage.yml", 15 | ".github/workflows/upgrade-compiler-dependencies.yml", 16 | ".github/workflows/upgrade-configuration.yml", 17 | ".github/workflows/upgrade-dev-dependencies.yml", 18 | ".github/workflows/upgrade-runtime-dependencies.yml", 19 | ".github/workflows/website.yml", 20 | ".gitignore", 21 | ".npmignore", 22 | ".projen/deps.json", 23 | ".projen/files.json", 24 | ".projen/tasks.json", 25 | "CODE_OF_CONDUCT.md", 26 | "DCO", 27 | "git-hooks/prepare-commit-msg", 28 | "git-hooks/README.md", 29 | "git-hooks/setup.sh", 30 | "LICENSE", 31 | "SECURITY.md", 32 | "tsconfig.dev.json", 33 | "tsconfig.json" 34 | ], 35 | "//": "~~ Generated by projen. To modify, edit .projenrc.ts and run \"npx projen\"." 36 | } 37 | -------------------------------------------------------------------------------- /.projen/tasks.json: -------------------------------------------------------------------------------- 1 | { 2 | "tasks": { 3 | "build": { 4 | "name": "build", 5 | "description": "Full release build", 6 | "steps": [ 7 | { 8 | "spawn": "default" 9 | }, 10 | { 11 | "spawn": "pre-compile" 12 | }, 13 | { 14 | "spawn": "compile" 15 | }, 16 | { 17 | "spawn": "post-compile" 18 | }, 19 | { 20 | "spawn": "test" 21 | }, 22 | { 23 | "spawn": "package" 24 | } 25 | ] 26 | }, 27 | "clobber": { 28 | "name": "clobber", 29 | "description": "hard resets to HEAD of origin and cleans the local repo", 30 | "env": { 31 | "BRANCH": "$(git branch --show-current)" 32 | }, 33 | "steps": [ 34 | { 35 | "exec": "git checkout -b scratch", 36 | "name": "save current HEAD in \"scratch\" branch" 37 | }, 38 | { 39 | "exec": "git checkout $BRANCH" 40 | }, 41 | { 42 | "exec": "git fetch origin", 43 | "name": "fetch latest changes from origin" 44 | }, 45 | { 46 | "exec": "git reset --hard origin/$BRANCH", 47 | "name": "hard reset to origin commit" 48 | }, 49 | { 50 | "exec": "git clean -fdx", 51 | "name": "clean all untracked files" 52 | }, 53 | { 54 | "say": "ready to rock! (unpushed commits are under the \"scratch\" branch)" 55 | } 56 | ], 57 | "condition": "git diff --exit-code > /dev/null" 58 | }, 59 | "compile": { 60 | "name": "compile", 61 | "description": "Only compile", 62 | "steps": [ 63 | { 64 | "exec": "tsc --build" 65 | }, 66 | { 67 | "exec": "lerna run build" 68 | } 69 | ] 70 | }, 71 | "default": { 72 | "name": "default", 73 | "description": "Synthesize project files", 74 | "steps": [ 75 | { 76 | "exec": "ts-node --project tsconfig.dev.json .projenrc.ts" 77 | } 78 | ] 79 | }, 80 | "eject": { 81 | "name": "eject", 82 | "description": "Remove projen from the project", 83 | "env": { 84 | "PROJEN_EJECTING": "true" 85 | }, 86 | "steps": [ 87 | { 88 | "spawn": "default" 89 | } 90 | ] 91 | }, 92 | "eslint": { 93 | "name": "eslint", 94 | "description": "Runs eslint against the codebase", 95 | "env": { 96 | "ESLINT_USE_FLAT_CONFIG": "false" 97 | }, 98 | "steps": [ 99 | { 100 | "exec": "eslint --ext .ts,.tsx --fix --no-error-on-unmatched-pattern $@ src test build-tools projenrc .projenrc.ts", 101 | "receiveArgs": true 102 | } 103 | ] 104 | }, 105 | "install": { 106 | "name": "install", 107 | "description": "Install project dependencies and update lockfile (non-frozen)", 108 | "steps": [ 109 | { 110 | "exec": "yarn install --check-files" 111 | } 112 | ] 113 | }, 114 | "install:ci": { 115 | "name": "install:ci", 116 | "description": "Install project dependencies using frozen lockfile", 117 | "steps": [ 118 | { 119 | "exec": "yarn install --check-files --frozen-lockfile" 120 | } 121 | ] 122 | }, 123 | "package": { 124 | "name": "package", 125 | "description": "Creates the distribution package" 126 | }, 127 | "post-compile": { 128 | "name": "post-compile", 129 | "description": "Runs after successful compilation" 130 | }, 131 | "post-upgrade": { 132 | "name": "post-upgrade", 133 | "description": "Runs after upgrading dependencies" 134 | }, 135 | "pre-compile": { 136 | "name": "pre-compile", 137 | "description": "Prepare the project for compilation" 138 | }, 139 | "rotate-cdk8s-plus": { 140 | "name": "rotate-cdk8s-plus", 141 | "steps": [ 142 | { 143 | "exec": "ts-node src/rotate-cdk8s-plus.ts 32" 144 | } 145 | ] 146 | }, 147 | "test": { 148 | "name": "test", 149 | "description": "Run tests", 150 | "steps": [ 151 | { 152 | "exec": "lerna run test -- -u" 153 | } 154 | ] 155 | }, 156 | "upgrade-compiler-dependencies": { 157 | "name": "upgrade-compiler-dependencies", 158 | "description": "upgrade compiler dependencies", 159 | "env": { 160 | "CI": "0" 161 | }, 162 | "steps": [ 163 | { 164 | "exec": "npx npm-check-updates@16 --upgrade --target=minor --peer --no-deprecated --dep=dev --filter=typescript" 165 | }, 166 | { 167 | "exec": "yarn install --check-files" 168 | }, 169 | { 170 | "exec": "yarn upgrade typescript" 171 | }, 172 | { 173 | "exec": "npx projen" 174 | }, 175 | { 176 | "spawn": "post-upgrade" 177 | } 178 | ] 179 | }, 180 | "upgrade-configuration": { 181 | "name": "upgrade-configuration", 182 | "description": "upgrade configuration", 183 | "env": { 184 | "CI": "0" 185 | }, 186 | "steps": [ 187 | { 188 | "exec": "npx npm-check-updates@16 --upgrade --target=minor --peer --no-deprecated --dep=dev --filter=projen,@cdk8s/projen-common" 189 | }, 190 | { 191 | "exec": "yarn install --check-files" 192 | }, 193 | { 194 | "exec": "yarn upgrade projen @cdk8s/projen-common" 195 | }, 196 | { 197 | "exec": "npx projen" 198 | }, 199 | { 200 | "spawn": "post-upgrade" 201 | } 202 | ] 203 | }, 204 | "upgrade-dev-dependencies": { 205 | "name": "upgrade-dev-dependencies", 206 | "description": "upgrade dev dependencies", 207 | "env": { 208 | "CI": "0" 209 | }, 210 | "steps": [ 211 | { 212 | "exec": "npx npm-check-updates@16 --upgrade --target=minor --peer --no-deprecated --dep=dev --filter=@types/jest,cdk8s,cdk8s-cli,cdk8s-plus-30,cdk8s-plus-31,cdk8s-plus-32,eslint-import-resolver-typescript,eslint-plugin-import,jest,lerna,semver,ts-jest,ts-node" 213 | }, 214 | { 215 | "exec": "yarn install --check-files" 216 | }, 217 | { 218 | "exec": "yarn upgrade @stylistic/eslint-plugin @types/jest @types/node @typescript-eslint/eslint-plugin @typescript-eslint/parser cdk8s cdk8s-cli cdk8s-plus-30 cdk8s-plus-31 cdk8s-plus-32 constructs eslint-import-resolver-typescript eslint-plugin-import eslint jest jest-junit lerna semver ts-jest ts-node" 219 | }, 220 | { 221 | "exec": "npx projen" 222 | }, 223 | { 224 | "spawn": "post-upgrade" 225 | } 226 | ] 227 | }, 228 | "upgrade-runtime-dependencies": { 229 | "name": "upgrade-runtime-dependencies", 230 | "description": "upgrade runtime dependencies", 231 | "env": { 232 | "CI": "0" 233 | }, 234 | "steps": [ 235 | { 236 | "exec": "echo No dependencies to upgrade." 237 | } 238 | ] 239 | }, 240 | "watch": { 241 | "name": "watch", 242 | "description": "Watch & compile in the background", 243 | "steps": [ 244 | { 245 | "exec": "tsc --build -w" 246 | } 247 | ] 248 | } 249 | }, 250 | "env": { 251 | "PATH": "$(npx -c \"node --print process.env.PATH\")" 252 | }, 253 | "//": "~~ Generated by projen. To modify, edit .projenrc.ts and run \"npx projen\"." 254 | } 255 | -------------------------------------------------------------------------------- /.projenrc.ts: -------------------------------------------------------------------------------- 1 | import * as fs from 'fs'; 2 | import { Cdk8sTeamTypeScriptProject } from '@cdk8s/projen-common'; 3 | import { JobPermission } from 'projen/lib/github/workflows-model'; 4 | 5 | const SPEC_VERSION = fs.readFileSync('src/latest-k8s-version.txt', 'utf-8'); 6 | 7 | // the latest version of k8s we support 8 | const LATEST_SUPPORTED_K8S_VERSION = Number(SPEC_VERSION); 9 | 10 | const mainBranch = 'master'; 11 | 12 | const project = new Cdk8sTeamTypeScriptProject({ 13 | name: 'root', 14 | repoName: 'cdk8s', 15 | sampleCode: false, 16 | defaultReleaseBranch: mainBranch, 17 | pullRequestTemplate: false, 18 | release: false, 19 | devDeps: [ 20 | '@cdk8s/projen-common', 21 | '@types/jest', 22 | '@types/node', 23 | 'cdk8s', 24 | 'cdk8s-cli', 25 | 'constructs', 26 | 'lerna', 27 | 'semver', 28 | 'ts-jest', 29 | 'typescript', 30 | 'projen', 31 | ], 32 | projenrcTs: true, 33 | githubOptions: { 34 | mergify: false, 35 | }, 36 | }); 37 | 38 | for (let i = 0; i < 3; i++) { 39 | project.addDevDeps(`cdk8s-plus-${LATEST_SUPPORTED_K8S_VERSION - i}`); 40 | } 41 | 42 | project.gitignore.exclude('.vscode/'); 43 | project.gitignore.addPatterns('*.js'); 44 | project.gitignore.addPatterns('*.d.ts'); 45 | project.gitignore.addPatterns('dist/'); 46 | 47 | // enable mono-repo 48 | project.package.addField('private', true); 49 | project.package.addField('workspaces', { 50 | packages: [], 51 | }); 52 | 53 | // override the default test task to run test across the repo 54 | project.testTask.reset('lerna run test -- -u'); 55 | project.tasks.removeTask('test:watch'); 56 | project.tasks.removeTask('test:update'); 57 | project.tasks.removeTask('test:compile'); 58 | 59 | // no package task is needed 60 | project.packageTask.reset(); 61 | 62 | project.package.addPackageResolutions( 63 | // Pin version of @types/responselike and got, see: https://github.com/sindresorhus/got/issues/2129 64 | '@types/responselike@1.0.0', 65 | 'got@12.3.1', 66 | ); 67 | 68 | 69 | // construct the build task 70 | project.compileTask.exec('lerna run build'); 71 | 72 | // deploy website 73 | const workflow = project.github!.addWorkflow('website'); 74 | workflow.on({ push: { branches: [mainBranch] } }); 75 | workflow.addJobs({ 76 | deploy: { 77 | permissions: { 78 | contents: JobPermission.WRITE, 79 | }, 80 | runsOn: ['ubuntu-latest'], 81 | steps: [ 82 | { 83 | name: 'Checkout sources', 84 | uses: 'actions/checkout@v2', 85 | }, 86 | { 87 | name: 'Setup Node.js', 88 | uses: 'actions/setup-node@v2', 89 | }, 90 | { 91 | name: 'Setup Hugo', 92 | uses: 'peaceiris/actions-hugo@v2', 93 | with: { 94 | 'hugo-version': '0.68.3', 95 | 'extended': true, 96 | }, 97 | }, 98 | { 99 | name: 'Setup Python', 100 | uses: 'actions/setup-python@v2', 101 | with: { 102 | 'python-version': '3.x', 103 | 'architecture': 'x64', 104 | }, 105 | }, 106 | { 107 | name: 'Install dependencies', 108 | run: 'yarn install --frozen-lockfile', 109 | }, 110 | { 111 | name: 'Build Website', 112 | run: [ 113 | 'cd website', 114 | './build.sh', 115 | ].join('\n'), 116 | }, 117 | { 118 | name: 'Build Docs Site', 119 | run: './docs/build.sh website/public/docs', 120 | }, 121 | { 122 | name: 'Deploy', 123 | uses: 'peaceiris/actions-gh-pages@v3', 124 | with: { 125 | github_token: '${{ secrets.GITHUB_TOKEN }}', 126 | publish_dir: './website/public', 127 | }, 128 | }, 129 | ], 130 | }, 131 | }); 132 | 133 | // The API reference is generated when the website is built and released 134 | // on the main branch, so the files should not be committed to the repo. 135 | // See docs/build.sh. 136 | let packages = ['cdk8s']; 137 | for (let i = 0; i < 3; i++) { 138 | packages.push(`cdk8s-plus-${LATEST_SUPPORTED_K8S_VERSION - i}`); 139 | } 140 | for (const pkg of packages) { 141 | for (const language of ['java', 'typescript', 'python']) { 142 | project.gitignore.exclude(`/docs/reference/${pkg}/${language}.md`); 143 | } 144 | } 145 | 146 | // Projen task to update references to old versions of cdk8s-plus 147 | const versionTaskObject = project.addTask('rotate-cdk8s-plus'); 148 | versionTaskObject.exec('ts-node src/rotate-cdk8s-plus.ts ' + SPEC_VERSION); 149 | 150 | project.synth(); -------------------------------------------------------------------------------- /ADOPTERS.md: -------------------------------------------------------------------------------- 1 | # Who is using cdk8s? 2 | 3 | cdk8s has a variety of users and use cases. 4 | Many customers want to learn from others who have already implemented cdk8s in their environments. 5 | 6 | The following is a self-reported list of users to help identify adoption and points of contact. 7 | 8 | ## Community 9 | 10 | We have two slack channels where you can ask questions and share ideas. We hang out in both pretty often. 11 | 12 | - [#cdk8s](https://cloud-native.slack.com/archives/C02KCDACGTT) on the [CNCF workspace](https://communityinviter.com/apps/cloud-native/cncf). 13 | - [#cdk8s](https://cdk-dev.slack.com/archives/C0184GCBY4X) on the [cdk.dev workspace](https://cdk.dev/) 14 | 15 | ## Add yourself 16 | 17 | If you are using cdk8s please consider adding yourself as a user by opening a pull request to this file. 18 | If you are open to others contacting you about your use of cdk8s, add your Slack name or email address. 19 | 20 | ## Adopters (Alphabetical) 21 | 22 | | Organization | Description | Contacts | Link | 23 | | --- | --- | --- | --- | 24 | | [example] Amazon, Inc. | Building cdk8s and cdk8s+ | `@jgarr`, `@iliapolo` | [Announcing GA for cdk8s](https://aws.amazon.com/blogs/containers/announcing-the-general-availability-of-cdk8s-and-support-for-go/) | 25 | | 8gears Container Registry | With cdk8s we dynamically generate manifests for different destinations of our Harbor-based SaaS. Multi-Cloud, Edge. | `@vad1mo` | [container-registry.com](https://container-registry.com/) | 26 | | Canida | Using cdk8s to generate Kubernetes manifests which are deployed to AWS EKS via ArgoCD | `nico@canida.io` | [Canida](https://canida.io) | 27 | | Cloudflare | Using cdk8s to manage large multi-tenant clusters with low drift and high velocity | `@heckler1` | [Cloudflare](https://www.cloudflare.com) | 28 | | Concrete Genius | CDK and cdk8s are used to manage our AWS and local development infrastructure | `@njlaw` | [Concrete Genius](https://concretegenius.com) | 29 | | Datamole | Relying on seamless CDK - CDK8s interoperability to manage AWS EKS workloads | `@datamole-ai` | [Datamole](https://www.datamole.ai/) | 30 | | Finimize | Using both CDK and cdk8s to create a consistent experience when describing our IaC | `@pykita` | [Finimize](https://finimize.com/) | 31 | | Griffin | Using CDK, CDK8s, and CDK8s+ to manage our AWS infra and EKS workloads | `@dancmeyers` | [Griffin](https://griffin.com/) | 32 | | PreciseTarget | We use cdk8s to manage all applications running in kubernetes across mulitple clusters. | `@steven-esser` | [PreciseTarget](https://www.precisetarget.com) | 33 | | The Home Depot | Using cdk8s to manage large, multi-tenant Kubernetes clusters with strong consistency across teams. | `@shinebayar-g` | [TheHomeDepot](https://www.homedepot.com/) | 34 | 35 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | cdk8s is maintained via 3 repostories, each publishing their own modules. 4 | 5 | You can see each individual module changelog by visiting the releases page of each repository: 6 | 7 | - [cdk8s](https://github.com/cdk8s-team/cdk8s-core/releases) (Note that the `cdk8s` package is maintained in the `cdk8s-team/cdk8s-core` repository) 8 | - [cdk8s-cli](https://github.com/cdk8s-team/cdk8s-cli/releases) 9 | - [cdk8s-plus](https://github.com/cdk8s-team/cdk8s-plus/releases) -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | The cdk8s project follows the [CNCF Community Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). -------------------------------------------------------------------------------- /DCO: -------------------------------------------------------------------------------- 1 | Developer Certificate of Origin 2 | Version 1.1 3 | 4 | Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 5 | 6 | Everyone is permitted to copy and distribute verbatim copies of this 7 | license document, but changing it is not allowed. 8 | 9 | 10 | Developer's Certificate of Origin 1.1 11 | 12 | By making a contribution to this project, I certify that: 13 | 14 | (a) The contribution was created in whole or in part by me and I 15 | have the right to submit it under the open source license 16 | indicated in the file; or 17 | 18 | (b) The contribution is based upon previous work that, to the best 19 | of my knowledge, is covered under an appropriate open source 20 | license and I have the right under that license to submit that 21 | work with modifications, whether created in whole or in part 22 | by me, under the same open source license (unless I am 23 | permitted to submit under a different license), as indicated 24 | in the file; or 25 | 26 | (c) The contribution was provided directly to me by some other 27 | person who certified (a), (b) or (c) and I have not modified 28 | it. 29 | 30 | (d) I understand and agree that this project and the contribution 31 | are public and that a record of the contribution (including all 32 | personal information I submit with it, including my sign-off) is 33 | maintained indefinitely and may be redistributed consistent with 34 | this project or the open source license(s) involved. -------------------------------------------------------------------------------- /OWNERS.md: -------------------------------------------------------------------------------- 1 | # Maintainers 2 | 3 | * Eli Polonsky [@iliapolo](https://github.com/iliapolo) 4 | * Vinayak Kukreja [@vinayak-kukreja](https://github.com/vinayak-kukreja) 5 | * Sumu Pitchayan [@sumupitchayan](https://github.com/sumupitchayan) 6 | * Evgeny Karasik [@evgenyka](https://github.com/evgenyka) 7 | * Uday Pant [@udaypant](https://github.com/udaypant) 8 | * Nathan Taber [@tabern](https://github.com/tabern) 9 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Cloud Development Kit for Kubernetes 2 | 3 | ![](./website/static/images/animation.gif) 4 | 5 | [![Website](https://github.com/cdk8s-team/cdk8s/workflows/website/badge.svg)](https://github.com/cdk8s-team/cdk8s/actions/workflows/website.yml) 6 | 7 | [![View on Construct Hub](https://constructs.dev/badge?package=cdk8s)](https://constructs.dev/packages/cdk8s) 8 | 9 | **cdk8s** is an open-source software development framework for defining Kubernetes applications and reusable abstractions using familiar 10 | programming languages and rich object-oriented APIs. cdk8s apps synthesize into standard Kubernetes 11 | manifests which can be applied to any Kubernetes cluster. 12 | 13 | cdk8s is a [Cloud Native Computing Foundation](https://www.cncf.io) Sandbox Project, built with ❤️ at AWS. We encourage you to [try it out](#getting-started), [leave feedback](#help--feedback), and [jump in to help](#contributing)! 14 | 15 | Contents: 16 | 17 | - [Repositories](#repositories) 18 | - [Overview](#overview) 19 | - [Getting Started](#getting-started) 20 | - [Help \& Feedback](#help--feedback) 21 | - [Documentation](#documentation) 22 | - [Examples](#examples) 23 | - [Roadmap](#roadmap) 24 | - [Community](#community) 25 | - [Contributing](#contributing) 26 | - [CDK8s.io website](#cdk8sio-website) 27 | - [License](#license) 28 | 29 | ## Repositories 30 | 31 | This project consists of multiple packages, maintained and released via the following repositories: 32 | 33 | - [cdk8s](https://github.com/cdk8s-team/cdk8s-core) - Core library. For historical reasons note that the [`cdk8s`](https://www.npmjs.com/package/cdk8s) package is maintained in the `cdk8s-team/cdk8s-core` repository. 34 | - [cdk8s-cli](https://github.com/cdk8s-team/cdk8s-cli) - Command-Line interface. 35 | - [cdk8s-plus](https://github.com/cdk8s-team/cdk8s-plus) - High-Level constructs for Kubernetes core. 36 | 37 | The current repository acts as an umbrella repository for cross module concerns, as well as the deployment of [`cdk8s.io`](https://cdk8s.io) 38 | 39 | ## Overview 40 | 41 | **cdk8s** apps are programs written in one of the supported programming 42 | languages. They are structured as a tree of 43 | [constructs](https://github.com/aws/constructs). 44 | 45 | The root of the tree is an `App` construct. Within an app, users define any 46 | number of charts (classes that extend the `Chart` class). Each chart is 47 | synthesized into a separate Kubernetes manifest file. Charts are, in turn, 48 | composed of any number of constructs, and eventually from resources, which 49 | represent any Kubernetes resource, such as `Pod`, `Service`, `Deployment`, 50 | `ReplicaSet`, etc. 51 | 52 | cdk8s apps only ***define*** Kubernetes applications, they don't actually apply 53 | them to the cluster. When an app is executed, it *synthesizes* all the charts 54 | defined within the app into the `dist` directory, and then those charts can be 55 | applied to any Kubernetes cluster using `kubectl apply -f dist/chart.k8s.yaml` or a GitOps tool like [Flux](https://fluxcd.io/). 56 | 57 | > **cdk8s** is based on the design concepts and technologies behind the [AWS 58 | Cloud Development Kit](https://aws.amazon.com/cdk), and can interoperate with 59 | AWS CDK constructs to define cloud-native applications that include both 60 | Kubernetes resources and other CDK constructs as first class citizens. 61 | 62 | Read [our blog](https://aws.amazon.com/blogs/containers/introducing-cdk-for-kubernetes/) or [watch our CNCF webinar](https://www.cncf.io/webinars/end-yaml-engineering-with-cdk8s/) to learn more and see a live demo of cdk8s in action. 63 | 64 | ## Getting Started 65 | 66 | See the [Getting Started](https://cdk8s.io/docs/latest/get-started) guide in 67 | [cdk8s Documentation](https://cdk8s.io/docs/). 68 | 69 | ## Help & Feedback 70 | 71 | Interacting with the community and the development team is a great way to 72 | contribute to the project. Please consider the following venues (in order): 73 | 74 | - Search [open issues](https://github.com/cdk8s-team/cdk8s/issues) 75 | - Stack Overflow: [cdk8s](https://stackoverflow.com/questions/tagged/cdk8s) 76 | - File a [new issue](https://github.com/cdk8s-team/cdk8s/issues/new/choose) 77 | - Slack: #cdk8s channel in [cdk.dev](https://cdk.dev) 78 | 79 | ## Documentation 80 | 81 | See [cdk8s Documentation](https://cdk8s.io/docs). 82 | 83 | ## Examples 84 | 85 | See our [Examples Directory](./examples). 86 | 87 | ## Roadmap 88 | 89 | See our [roadmap](https://github.com/cdk8s-team/cdk8s/projects/1) for details about our plans for the project. 90 | 91 | ## Community 92 | 93 | See [Awesome cdk8s](https://github.com/dungahk/awesome-cdk8s). 94 | 95 | If you're a cdk8s user please consider adding your name to the [ADOPTERS](./ADOPTERS.md) file. 96 | 97 | ## Contributing 98 | 99 | The cdk8s project adheres to the [CNCF Code of 100 | Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). 101 | 102 | We welcome community contributions and pull requests. See our [contribution 103 | guide](./CONTRIBUTING.md) for more information on how to report issues, set up a 104 | development environment and submit code. 105 | 106 | ## CDK8s.io website 107 | 108 | See [Docs Directory](./docs/README.md). 109 | 110 | ## License 111 | 112 | This project is distributed under the [Apache License, Version 2.0](./LICENSE). 113 | 114 | -------------------------------------------------------------------------------- /ROADMAP.md: -------------------------------------------------------------------------------- 1 | # Roadmap 2 | 3 | The project roadmap is under discussion. 4 | 5 | > See https://github.com/cdk8s-team/cdk8s/discussions/2052 6 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Reporting a Vulnerability 2 | 3 | If you discover a potential security issue in this project we ask that you notify the cdk8s team directly via email to cncf-cdk8s-security@lists.cncf.io. 4 | 5 | **Please do not create a public GitHub issue.** -------------------------------------------------------------------------------- /docs/.gitignore: -------------------------------------------------------------------------------- 1 | !*.js 2 | 3 | # These are copied from outside during build.sh 4 | CHANGELOG.md 5 | CONTRIBUTING.md 6 | ROADMAP.md 7 | plus/* 8 | !plus/.pages 9 | !plus/index.md 10 | -------------------------------------------------------------------------------- /docs/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - What is cdk8s?: index.md 3 | - Getting started: get-started 4 | - basics 5 | - cdk8s+: plus 6 | - CLI: cli 7 | - API Reference: reference 8 | - examples 9 | - ecosystem-interoperability.md 10 | - migrating-from-1.x.md 11 | - Support: 12 | - Issues: https://github.com/cdk8s-team/cdk8s/issues/ 13 | - Report a new issue: https://github.com/cdk8s-team/cdk8s/issues/new/choose 14 | - Stack overflow: https://stackoverflow.com/questions/tagged/cdk8s 15 | - Slack: https://cdk.dev 16 | - Mailing list: https://groups.google.com/forum/#!forum/cdk8s 17 | - CHANGELOG.md 18 | - ROADMAP.md 19 | - Contribution guide: CONTRIBUTING.md 20 | - Media: media.md 21 | -------------------------------------------------------------------------------- /docs/assets/animation.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/docs/assets/animation.gif -------------------------------------------------------------------------------- /docs/assets/corevsplus.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/docs/assets/corevsplus.png -------------------------------------------------------------------------------- /docs/assets/extra.css: -------------------------------------------------------------------------------- 1 | :root { 2 | --md-primary-fg-color: #215276; 3 | --md-primary-fg-color--light: #d8e3ea; 4 | --md-primary-fg-color--dark: #14354f; 5 | } 6 | 7 | h5 { 8 | text-transform: none !important; 9 | } 10 | 11 | .md-source__fact--version { 12 | display: none; 13 | } 14 | 15 | /* Search key hint. @see https://github.com/squidfunk/mkdocs-material/issues/2574 */ 16 | [data-md-toggle="search"]:not(:checked) ~ .md-header .md-search__form::after { 17 | position: absolute; 18 | top: .3rem; 19 | right: .3rem; 20 | display: block; 21 | padding: .1rem .4rem; 22 | color: var(--md-default-bg-color); 23 | font-weight: bold; 24 | font-size: .8rem; 25 | border: .05rem solid var(--md-default-bg-color--lighter); 26 | border-radius: .1rem; 27 | content: "/"; 28 | } 29 | 30 | /* Hide the left nav title. It's the same as site title in the header. */ 31 | .md-nav--primary > .md-nav__title{ 32 | display: none; 33 | } 34 | -------------------------------------------------------------------------------- /docs/assets/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/docs/assets/favicon.png -------------------------------------------------------------------------------- /docs/assets/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/docs/assets/logo.png -------------------------------------------------------------------------------- /docs/assets/logos/cdk8s-vectors.ai: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/docs/assets/logos/cdk8s-vectors.ai -------------------------------------------------------------------------------- /docs/assets/logos/horizontal/cdk8s.horizontal.black.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/docs/assets/logos/horizontal/cdk8s.horizontal.black.png -------------------------------------------------------------------------------- /docs/assets/logos/horizontal/cdk8s.horizontal.color.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/docs/assets/logos/horizontal/cdk8s.horizontal.color.png -------------------------------------------------------------------------------- /docs/assets/logos/horizontal/cdk8s.horizontal.white.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/docs/assets/logos/horizontal/cdk8s.horizontal.white.png -------------------------------------------------------------------------------- /docs/assets/logos/icon/cdk8s.icon.black.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/docs/assets/logos/icon/cdk8s.icon.black.png -------------------------------------------------------------------------------- /docs/assets/logos/icon/cdk8s.icon.color.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/docs/assets/logos/icon/cdk8s.icon.color.png -------------------------------------------------------------------------------- /docs/assets/logos/icon/cdk8s.icon.white.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/docs/assets/logos/icon/cdk8s.icon.white.png -------------------------------------------------------------------------------- /docs/assets/logos/stacked/cdk8s.stacked.black.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/docs/assets/logos/stacked/cdk8s.stacked.black.png -------------------------------------------------------------------------------- /docs/assets/logos/stacked/cdk8s.stacked.color.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/docs/assets/logos/stacked/cdk8s.stacked.color.png -------------------------------------------------------------------------------- /docs/assets/logos/stacked/cdk8s.stacked.white.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/docs/assets/logos/stacked/cdk8s.stacked.white.png -------------------------------------------------------------------------------- /docs/assets/opengraph.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/docs/assets/opengraph.jpg -------------------------------------------------------------------------------- /docs/basics/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - index.md 3 | - constructs.md 4 | - chart.md 5 | - api-object.md 6 | - deps.md 7 | - ... 8 | - testing.md 9 | -------------------------------------------------------------------------------- /docs/basics/api-object.md: -------------------------------------------------------------------------------- 1 | # ApiObject 2 | 3 | An `ApiObject` is a construct that represents an entry in a Kubernetes manifest (level 0). 4 | In most cases, you won't use `ApiObject` directly but rather use classes that 5 | are imported through `cdk8s import` and which extend this base class. 6 | 7 | By default, when you import API objects from k8s, all class names will all be 8 | prefixed with `Kube` to differentiate them from the high-level APIs in cdk8s+. 9 | It is possible to customize the prefix by providing a string value to the 10 | `--class-prefix` flag, or by passing `--no-class-prefix`. (Note: if no prefix is 11 | used for k8s resources, this may lead to conflicts - see 12 | https://github.com/cdk8s-team/cdk8s/issues/140). 13 | 14 | ### Resource Names 15 | 16 | By default, cdk8s will autogenerate a name for every resource when it is instantiated. 17 | The name is created from the path of the construct, and suffixed with a hash of that path. 18 | 19 | For example, the following code: 20 | 21 | ```ts 22 | import { App, Chart } from 'cdk8s'; 23 | import * as kplus from 'cdk8s-plus-32'; 24 | 25 | const app = new App(); 26 | const chart = new MyChart(app, 'my-chart'); 27 | 28 | new kplus.Deployment(chart, 'deployment', { 29 | containers: [{ image: 'nginx' }] 30 | }); 31 | 32 | app.synth(); 33 | ``` 34 | 35 | generates a `Deployment` with the name: `my-chart-deployment-c8c354dd`. Where `my-chart` is the id of the `Chart`, `deployment` is the id of the `Deployment`, and `c8c354dd` is the hash suffix. 36 | 37 | You can programmatically access the name of any resource in a cdk8s app by accessing the `.name` property of a resource. For example: 38 | 39 | ```ts 40 | const deployment = new kplus.Deployment(chart, 'deployment', { 41 | containers: [{ image: 'nginx' }] 42 | }); 43 | const deploymentName = deployment.name; 44 | ``` 45 | 46 | To remove hashes from resource names, you can set the `disableResourceNameHashes` property to `true`: 47 | 48 | ```ts 49 | ... 50 | const chart = new MyChart(app, 'my-chart', { 51 | disableResourceNameHashes: true, 52 | }); 53 | ... 54 | ``` 55 | Which would similarly generate a `Deployment` with the name: `my-chart-deployment`. Note that disabling hashes introduces the possibility of name clashes. For example, the following code: 56 | 57 | ```ts 58 | // think of this as a custom construct 59 | const c = new Construct(this, 'Construct'); 60 | 61 | new kplus.Deployment(c, 'Deployment', { 62 | containers: [{ image: 'image' }] 63 | }); 64 | 65 | new kplus.Deployment(this, 'Construct-Deployment', { 66 | containers: [{ image: 'image' }] 67 | }) 68 | ``` 69 | 70 | will produce two deployments with the same name: `chart-construct-deployment`. 71 | This happens because cdk8s uses a hyphen (`-`) as the delimiter between elements 72 | in the path, so if the id of your construct also contains a hyphen (`-`), a collision 73 | can occur. In addition, you can explicitly set a name for every resource by using the `metadata.name` property: 74 | 75 | ```ts 76 | new kplus.Deployment(c, 'Deployment', { 77 | metadata: { 78 | name: 'my-deployment' 79 | }, 80 | ... 81 | }); 82 | ``` 83 | -------------------------------------------------------------------------------- /docs/basics/app.md: -------------------------------------------------------------------------------- 1 | # App 2 | 3 | The `App` is the entry-point of your `cdk8s` application, and is the root of the constructs tree. 4 | Every application first starts by creating an instance of an `App`. 5 | 6 | ```ts 7 | import { App } from 'cdk8s'; 8 | 9 | const app = new App(); 10 | ``` 11 | 12 | Then, [Charts](./chart.md) are registered into the app: 13 | 14 | ```ts 15 | new MyChart(app, 'Chart'); 16 | ``` 17 | 18 | And finally, the `app` is synthesized in order to produce the YAML manifests. Overall, your `cdk8s` 19 | application will have the following high level structure to it: 20 | 21 | ```ts 22 | import { App } from 'cdk8s'; 23 | 24 | // create the app entry-point 25 | const app = new App(); 26 | 27 | // register charts to the app 28 | new MyChart(app, 'Chart'); 29 | 30 | // synthesize the app 31 | app.synth(); 32 | ``` 33 | 34 | ## Resolvers 35 | 36 | Resolvers are a mechanism to inject custom logic into the cdk8s value resolution process. 37 | It allows to transform any value just before being written to the Kubernetes manifest. 38 | 39 | For example, lets create a resolver that adds a prefix to every resource in our application. 40 | To define a custom resolver, create a class that implements the `IResolver` interface: 41 | 42 | ```ts 43 | import { IResolver, ResolutionContext } from 'cdk8s'; 44 | 45 | export class AddNamePrefixResolver implements IResolver { 46 | 47 | constructor(private readonly prefix: string) {} 48 | 49 | public resolve(context: ResolutionContext): void { 50 | 51 | // check if we are resolving the name property 52 | const isNameProperty = context.key.includes('metadata') && context.key.includes('name') && context.key.length === 2; 53 | 54 | // check we haven't already added a prefix. this is important because 55 | // resolution is recursive, so we need to avoid infinite recursion. 56 | const isPrefixed = typeof(context.value) === 'string' && context.value.startsWith(this.prefix); 57 | 58 | if (isNameProperty && !isPrefixed) { 59 | // replace the value with a new one 60 | context.replaceValue(`${this.prefix}${context.value}`); 61 | } 62 | } 63 | 64 | } 65 | ``` 66 | 67 | The `context` argument contains information about the value that is currently being resolved: 68 | 69 | - **obj**: `ApiObject` currently being resolved. 70 | - **key**: Array containing the JSON path elements of the keys leading up to the value. 71 | - **value**: The original value. 72 | 73 | It also contains the `replaceValue` method you should use to set a replacement value instead of the original. 74 | When you create a cdk8s `App`, pass the resolver instance to it via the `resolvers` property: 75 | 76 | ```ts 77 | import { App, Chart } from 'cdk8s' 78 | 79 | const app = new App({ resolvers: [new AddNamePrefixResolver('custom-prefix')] }); 80 | new Chart(app, 'Chart'); 81 | ``` 82 | 83 | When you run `cdk8s synth`, your custom logic will be invoked, allowing you to replace the 84 | original value. 85 | 86 | > When passing multiple resolvers, the first one (by natural order of the array) that invokes `replaceValue` is considered, and others are ignored. 87 | 88 | One common use-case for resolvers is to fetch values from deployed infrastructure. 89 | This allows authoring cdk8s applications that natively leverage managed cloud resources. 90 | To that end, two specific resolvers are available that allow you to integrate cdk8s with other CDK frameworks: 91 | 92 | - [AWS CDK Resolver](https://github.com/cdk8s-team/cdk8s-awscdk-resolver) 93 | - [CDK For Terraform Resolver](https://github.com/cdk8s-team/cdk8s-cdktf-resolver) -------------------------------------------------------------------------------- /docs/basics/chart.md: -------------------------------------------------------------------------------- 1 | # Chart 2 | 3 | The `Chart` is a container that synthesizes a single Kubernetes manifest. 4 | 5 | ```ts 6 | class MyChart extends Chart { 7 | constructor(scope: Construct, ns: string) { 8 | super(scope, ns); 9 | 10 | // add contents here 11 | } 12 | } 13 | ``` 14 | 15 | During synthesis, charts collect all the `ApiObject` nodes (recursively) and 16 | emit a single YAML manifest that includes all these objects. 17 | 18 | When a chart is defined, you can specify chart-level `namespace` and `labels`. 19 | Those will be applied to all API objects defined within the chart (recursively): 20 | 21 | ```ts 22 | class MyChart extends Chart { 23 | constructor(scope: Construct, ns: string) { 24 | super(scope, ns, { 25 | namespace: 'my-namespace', 26 | labels: { 27 | app: 'my-app', 28 | }, 29 | }); 30 | 31 | new ApiObject(this, 'my-object', { 32 | apiVersion: 'v1', 33 | kind: 'Foo' 34 | }); 35 | } 36 | } 37 | ``` 38 | 39 | Will synthesize into: 40 | 41 | ```yaml 42 | apiVersion: v1 43 | kind: Foo 44 | metadata: 45 | namespace: my-namespace 46 | labels: 47 | app: my-app 48 | ``` 49 | -------------------------------------------------------------------------------- /docs/basics/constructs.md: -------------------------------------------------------------------------------- 1 | # Constructs 2 | 3 | Constructs are the basic building block of **cdk8s**. They are the instrument 4 | that enables composition and creation of higher-level abstractions through 5 | normal object-oriented classes. 6 | 7 | If you come from the Kubernetes world, you can think of constructs as 8 | programmatically defined Helm Charts. The nice thing about constructs being 9 | "programmatically defined" is that we can use them to leverage the full power of 10 | object-oriented programming. For example: 11 | 12 | * You can express the abstraction's API using strong-typed data types 13 | * You can express rich interactions with methods and properties 14 | * You can create polymorphic programming models through interfaces and base 15 | classes 16 | * Share them through regular package managers 17 | * Test them using our familiar testing tools and techniques 18 | * Version them 19 | * ...and do all that stuff that we've been doing with software in the past 20 20 | years. 21 | -------------------------------------------------------------------------------- /docs/basics/deps.md: -------------------------------------------------------------------------------- 1 | # Dependencies 2 | 3 | You can declare dependencies between any two cdk8s constructs using the `addDependency()` method. 4 | 5 | ### ApiObjects 6 | 7 | For example, you can force kubernetes to first apply a `Namespace` before applying the `Service` in the scope of that namespace: 8 | 9 | ```typescript 10 | 11 | const namespace = new k8s.KubeNamespace(chart, 'backend'); 12 | const service = new k8s.KubeService(chart, 'Service', { metadata: { namespace: namespace.name }}); 13 | 14 | // declare the dependency. this is just a syntactic sugar for Node.of(service).addDependency(namespace) 15 | service.addDependency(namespace); 16 | ``` 17 | 18 | `cdk8s` will ensure that the `Namespace` object is placed before the `Service` object in the resulting manifest: 19 | 20 | ```yaml 21 | apiVersion: v1 22 | kind: Namespace 23 | metadata: 24 | name: chart-backend-a59d2e47 25 | --- 26 | apiVersion: v1 27 | kind: Service 28 | metadata: 29 | name: chart-service-93d02be7 30 | namespace: chart-backend-a59d2e47 31 | ``` 32 | 33 | ### Charts 34 | 35 | You can also specify dependencies between charts, in exactly the same manner. For example, if we have a chart that provisions our `namespace`, we need that chart to be applied first: 36 | 37 | ```typescript 38 | const namespaceChart = new Chart(app, 'namespace'); 39 | const applicationChart = new Chart(app, 'application'); 40 | 41 | // declare the dependency. this is just a syntactic sugar for Node.of(applicationChart).addDependency(namespaceChart) 42 | applicationChart.addDependency(namespaceChart); 43 | ``` 44 | 45 | Running `cdk8s synth` will produce the following `dist` directory: 46 | 47 | ```console 48 | > cdk8s synth 49 | 50 | dist/0000-namespace.k8s.yaml 51 | dist/0001-application.k8s.yaml 52 | ``` 53 | 54 | Notice that the `namespace` chart appears first with the `0000` prefix. This will ensure that a subsequent execution of `kubectl apply -f dist/` will apply the `namespace` first, and the `application` second. 55 | 56 | ### Custom Constructs 57 | 58 | The behavior above applies in the same way to custom constructs that you create or use. 59 | 60 | ```typescript 61 | class Database extends Construct { 62 | constructor(scope: Construct, name: string) { 63 | super(scope, name); 64 | 65 | new k8s.KubeStatefulSet(this, 'StatefulSet'); 66 | new k8s.KubeConfigMap(this, 'ConfigMap'); 67 | } 68 | } 69 | 70 | const app = new App(); 71 | 72 | const chart = new Chart(app, 'Chart'); 73 | 74 | const service = new k8s.KubeService(chart, 'Service') 75 | const database = new Database(chart, 'Database'); 76 | 77 | service.addDependency(database); 78 | ``` 79 | 80 | Declaring such a dependency will cause **each** `ApiObject` in the source construct, to *depend on* **every** `ApiObject` in the target construct. 81 | 82 | Note that in the example above, the source construct is actually an `ApiObject`, which is also ok since it is essentially a construct with a single `ApiObject`. 83 | 84 | > Note that if the source of your dependency is a custom construct, it won't have the `addDependency` syntactic sugar by default, so you'll have to use `Node.of()`. 85 | 86 | The resulting manifest will be: 87 | 88 | ```yaml 89 | apiVersion: apps/v1 90 | kind: StatefulSet 91 | metadata: 92 | name: chart-database-statefulset-4627f8e2 93 | --- 94 | apiVersion: v1 95 | kind: ConfigMap 96 | metadata: 97 | name: chart-database-configmap-676f8640 98 | --- 99 | apiVersion: v1 100 | kind: Service 101 | metadata: 102 | name: chart-service-93d02be7 103 | ``` 104 | 105 | You can see that all `ApiObject`s of the `Database` construct, appear before the `Service` object. 106 | 107 | ### Things just got cool 108 | 109 | If you simply declare a dependency between two `ApiObject`s (or `Constructs`), that belong to two different `Chart`s, `cdk8s` will create the chart dependency automatically for you. 110 | 111 | ```typescript 112 | const namespaceChart = new Chart(app, 'namespace'); 113 | const applicationChart = new Chart(app, 'application'); 114 | 115 | const namespace = new k8s.KubeNamespace(namespaceChart, 'namespace'); 116 | const deployment = new k8s.KubeDeployment(applicationChart, 'Deployment'); 117 | 118 | // dependency between ApiObjects, not Charts! 119 | deployment.addDependency(namespace); 120 | ``` 121 | 122 | Running `cdk8s synth` will produce the same result as if explicit chart dependencies were declared: 123 | 124 | ```console 125 | > cdk8s synth 126 | 127 | dist/0000-namespace.k8s.yaml 128 | dist/0001-application.k8s.yaml 129 | ``` 130 | 131 | This means you need not be bothered with managing chart dependencies, simply work with the `ApiObject`s you create, and let `cdk8s` infer the chart dependencies. 132 | -------------------------------------------------------------------------------- /docs/basics/escape-hatches.md: -------------------------------------------------------------------------------- 1 | # Escape Hatches 2 | 3 | An "escape hatch" is an intentional _leak_ in the abstraction layer. It allows 4 | users to "escape the abstraction" and reach out to a lower layer. 5 | 6 | Similarly, in CDKs, escape hatches are mechanisms that allow users to tweak the 7 | synthesized output when the abstraction they use does not "hold water". 8 | 9 | You may need to use an escape hatch in the following cases: 10 | 11 | 1. You are using an imported API object (e.g. `KubeDeployment`) and there is an 12 | issue with the schema or a bug in "import" which results in an invalid 13 | manifest or missing fields (as an example see 14 | [issue #140](https://github.com/cdk8s-team/cdk8s/issues/140)). 15 | 2. You are using a high-level API (e.g. cdk8s+) which does not expose some 16 | functionality which exists in the lower-level resources. 17 | 18 | ## Patching API objects directly 19 | 20 | The [`ApiObject`](./api-object.md) class, which is the base of all objects 21 | synthesized into a Kubernetes manifest offers an API for patching the 22 | synthesized output at the wire level using JSON Patch 23 | ([RFC-6902](http://tools.ietf.org/html/rfc6902)): 24 | 25 | ```ts 26 | import { JsonPatch } from 'cdk8s'; 27 | apiObject.addJsonPatch(JsonPatch.replace('/foo', 'bar')); 28 | apiObject.addJsonPatch(JsonPatch.add('/foo/bar/0', { bar: 123 })); 29 | ``` 30 | 31 | During synthesis, patches are applied in-order after the API object synthesized 32 | itself. 33 | 34 | All classes generated using the CLI [import](../cli/import.md) command extend 35 | `ApiObject`, and therefore include the `addJsonPatch()` method. 36 | 37 | ## Patching API objects behind higher-level APIs 38 | 39 | The second use case for using escape hatches is when you are working against a 40 | higher-level construct which, for some reason, does not allow you to achieve 41 | what you need. 42 | 43 | For example, let's say you are using the `Pod` class from cdk8s+ and you wish to 44 | set [`enableServiceLinks`] to `true`. This feature is currently not supported in 45 | the cdk8s+ `Pod` API, so you'll want to patch the underlying `KubePod` and set 46 | this value. 47 | 48 | [`enableServiceLinks`]: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#podspec-v1-core 49 | 50 | To do that, you will need to "peak" into the construct tree and find the underlying 51 | API object, so you can apply the patch to it: 52 | 53 | ```ts 54 | import { Pod } from 'cdk8s-plus-32'; 55 | import { ApiObject } from 'cdk8s'; 56 | 57 | const pod = new Pod(...); 58 | const kubePod = ApiObject.of(pod); 59 | kubePod.addJsonPatch(...); 60 | ``` 61 | 62 | The `ApiObject.of()` method uses capabilities of the [constructs programming 63 | model](./constructs.md) to find the "default child" of a construct 64 | (`Node.of(c).defaultChild`). When a construct is initialized, it can either 65 | explicitly assign the value of `Node.of(this).defaultChild = xxx` or it can use 66 | the identity `Default` for one of its child constructs. This will automatically 67 | identify it as the default child. 68 | 69 | !!! tip 70 | The `ApiObject.of()` method recursively searches down the construct tree 71 | through child constructs called `Default` until it finds a child of type 72 | `ApiObject`. This means, for example, that `ApiObject.of(apiObject)` returns 73 | the same object. 74 | 75 | There could be situations where a default child is not recorded by a high-level 76 | construct. This still does not mean you are blocked from patching the underlying 77 | API objects. You can still use `Node.of(x)` to traverse the construct tree to 78 | obtain the child. For example, you can use `Node.of(x).findChild(id)` to 79 | retrieve any child by its ID. 80 | -------------------------------------------------------------------------------- /docs/basics/helm.md: -------------------------------------------------------------------------------- 1 | # Helm Support 2 | 3 | You can use the `Helm` construct in order to include [Helm](https://helm.sh) 4 | charts. 5 | 6 | !!! note 7 | You will need helm to be [installed](https://helm.sh/docs/intro/install/) locally for this feature. 8 | For accessing private helm repositories, you must be authenticated to the repository in a way that the `helm pull` command recognizes. 9 | 10 | The following example adds the 11 | [bitnami/redis](https://github.com/bitnami/charts/tree/master/bitnami/redis) 12 | Helm chart with sentinel containers enabled: 13 | 14 | > The Bitnami helm repo needs to be added through: `helm repo add bitnami https://charts.bitnami.com/bitnami` 15 | 16 | > For accessing private helm repositories, you must be authenticated to the repository in a way that the `helm template` 17 | > command recognizes. 18 | 19 | ```ts 20 | class MyChart extends cdk8s.Chart { 21 | constructor(scope: Construct, id: string) { 22 | super(scope, id); 23 | 24 | const redis = new Helm(this, 'redis', { 25 | chart: 'bitnami/redis', 26 | values: { 27 | sentinel: { 28 | enabled: true 29 | } 30 | } 31 | }); 32 | } 33 | } 34 | ``` 35 | 36 | The `Helm` construct will render the manifest from the specified chart by 37 | executing `helm template`. If `values` is specified, these values will override 38 | the default values included with the chart. 39 | 40 | The `name` option can be used to specify the chart's [release name](https://helm.sh/docs/intro/using_helm/#three-big-concepts). 41 | If not specified, a valid and unique release name will be allocated 42 | based on the construct path. 43 | 44 | The `Helm` construct extends `Include` and inherits it's API. For example, you 45 | can use the `apiObjects` property to find and interact with included API 46 | objects. 47 | 48 | The following example shows how to add an annotation to the Redis master 49 | deployment: 50 | 51 | ```ts 52 | const master = redis.apiObjects.find(o => o.name === 'foo-redis-master'); 53 | master.metadata.addAnnotation('my.annotation', 'hey-there'); 54 | ``` 55 | -------------------------------------------------------------------------------- /docs/basics/include.md: -------------------------------------------------------------------------------- 1 | # Include 2 | 3 | The `Include` construct can be used to include an existing manifest in a chart. 4 | 5 | The following example will include the Kubernetes Dashboard in `MyChart`: 6 | 7 | ```ts 8 | import { Include } from 'cdk8s'; 9 | 10 | class MyChart extends Chart { 11 | constructor(scope: Construct, id: string) { 12 | super(scope, id); 13 | 14 | const dashboard = new Include(this, 'dashboard', { 15 | url: 'https://raw.githubusercontent.com/kubernetes/dashboard/v2.4.0/aio/deploy/recommended.yaml', 16 | // or 17 | url: 'dashboard.yaml' 18 | }); 19 | 20 | // ...other resources 21 | } 22 | } 23 | ``` 24 | 25 | All API objects defined in the included manifest will be added as children 26 | `ApiObject`s under the `Include` construct's scope and can be accessed 27 | through the `apiObject` property: 28 | 29 | The following example queries for all the `Deployment` resources in the 30 | dashboard: 31 | 32 | ```ts 33 | const deploymentApiObject = dashboard.apiObjects.find(c => c.kind === 'Deployment'); 34 | ``` 35 | 36 | NOTE: names of included objects (`metadata.name`) are preserved. This means that 37 | if you try to include the same manifest twice into the same chart, your manifest 38 | will have duplicate definitions of the same objects. 39 | -------------------------------------------------------------------------------- /docs/basics/index.md: -------------------------------------------------------------------------------- 1 | # Basic concepts of cdk8s 2 | 3 | This section discusses core concepts in cdk8s. 4 | 5 | !!! info 6 | 7 | The documentation here relates to version `2.x` of the cdk8s toolchain, which is the latest. If you are still using version `1.x`, please refer to the [Migrating from 1.x Guide](../migrating-from-1.x.md). 8 | -------------------------------------------------------------------------------- /docs/basics/testing.md: -------------------------------------------------------------------------------- 1 | # Testing 2 | 3 | cdk8s bundles a set of test utilities under the `Testing` class: 4 | 5 | * `Testing.app()` returns an `App` object bound to a temporary output directory. 6 | * `Testing.chart()` returns a `Chart` object bound to a testing app. 7 | * `Testing.synth(chart)` returns the Kubernetes manifest synthesized from a 8 | chart. 9 | -------------------------------------------------------------------------------- /docs/build.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | set -euo pipefail 3 | set -x 4 | 5 | scriptdir=$(cd $(dirname $0) && pwd) 6 | nodemodulesdir=${scriptdir}/../node_modules 7 | outdir=${1:-${scriptdir}/../website/static/docs} 8 | 9 | # resolve path 10 | mkdir -p "${outdir}" 11 | outdir=$(cd ${outdir} && pwd) 12 | 13 | # repo root 14 | cd ${scriptdir}/.. 15 | 16 | # install deps 17 | pip3 install -r docs/requirements.txt 18 | 19 | # stage some content from the repo 20 | cp CHANGELOG.md docs/ 21 | cp CONTRIBUTING.md docs/ 22 | cp ROADMAP.md docs/ 23 | 24 | LATEST_K8S_VERSION=$(< src/latest-k8s-version.txt) 25 | CDK8S_PLUS_VERSIONS=("cdk8s-plus-$((${LATEST_K8S_VERSION}-2))" "cdk8s-plus-$((${LATEST_K8S_VERSION}-1))" "cdk8s-plus-${LATEST_K8S_VERSION}") 26 | 27 | # copy API reference docs from cdk8s and each cdk8s+ package version 28 | for module in cdk8s ${CDK8S_PLUS_VERSIONS[@]}; do 29 | javamd=$(node -p "require.resolve('${module}/docs/java.md')") 30 | pythonmd=$(node -p "require.resolve('${module}/docs/python.md')") 31 | typescriptmd=$(node -p "require.resolve('${module}/docs/typescript.md')") 32 | cat $javamd | sed "s/# API Reference/# ${module} (Java)/" > "docs/reference/${module}/java.md" 33 | cat $pythonmd | sed "s/# API Reference/# ${module} (Python)/" > "docs/reference/${module}/python.md" 34 | cat $typescriptmd | sed "s/# API Reference/# ${module} (TypeScript)/" > "docs/reference/${module}/typescript.md" 35 | done 36 | 37 | # copy /plus/* docs from each cdk8s+ version into separate docs/plus/$version sub-dirs 38 | for module in ${CDK8S_PLUS_VERSIONS[@]}; do 39 | mkdir -p "docs/plus/${module}/" 40 | cp -R "${nodemodulesdir}/${module}"/docs/plus/* "docs/plus/${module}" 41 | done 42 | 43 | # repo root 44 | cd ${scriptdir}/.. 45 | 46 | docsout="${outdir}/latest" 47 | rm -fr ${docsout} 48 | mkdocs build --site-dir ${docsout} 49 | 50 | # create a redirect to the latest version 51 | echo "" > ${outdir}/index.html 52 | -------------------------------------------------------------------------------- /docs/cli/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - index.md 3 | - installation.md 4 | - init.md 5 | - import.md 6 | - synth.md 7 | - ... -------------------------------------------------------------------------------- /docs/cli/index.md: -------------------------------------------------------------------------------- 1 | # Command Line Interface (CLI) 2 | 3 | cdk8s is shipped with a command-line interface called `cdk8s` which can be used 4 | to work with cdk8s apps. 5 | 6 | The CLI is not required to use cdk8s but it includes some useful utilities. 7 | 8 | !!! info 9 | 10 | The documentation here relates to version `2.x` of the cdk8s toolchain, which is the latest. If you are still using version `1.x`, please refer to the [Migrating from 1.x Guide](../migrating-from-1.x.md). 11 | -------------------------------------------------------------------------------- /docs/cli/init.md: -------------------------------------------------------------------------------- 1 | # init 2 | 3 | This command creates new cdk8s projects from built-in templates: 4 | 5 | ```shell 6 | cdk8s init TEMPLATE 7 | ``` 8 | 9 | The following example will create a new TypeScript app project: 10 | 11 | ```shell 12 | mkdir my-fun-little-project 13 | cd my-fun-little-project 14 | cdk8s init typescript-app 15 | ``` 16 | -------------------------------------------------------------------------------- /docs/cli/installation.md: -------------------------------------------------------------------------------- 1 | # Install the cdk8s CLI 2 | 3 | This page describes the different ways you can install the Cloud Development Kit for Kubernetes (cdk8s) command-line interface (CLI) tool on your local machine. 4 | 5 | ## Installation 6 | ### Homebrew 7 | To install the cdk8s CLI with [Homebrew](https://brew.sh/), run the following command: 8 | ```console 9 | brew install cdk8s 10 | ``` 11 | 12 | ### npm 13 | To install the cdk8s CLI with [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm), run the following command: 14 | ```console 15 | npm i -g cdk8s-cli 16 | ``` 17 | 18 | ### Yarn 19 | To install the cdk8s CLI with [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable), run the following command: 20 | ```console 21 | yarn global add cdk8s-cli 22 | ``` 23 | 24 | ## Check version 25 | To check your version, run the following command: 26 | ```console 27 | cdk8s --version 28 | ``` 29 | You should see something similar to the following: 30 | ``` 31 | 2.2.31 32 | ``` -------------------------------------------------------------------------------- /docs/cli/synth.md: -------------------------------------------------------------------------------- 1 | # synth 2 | 3 | The `cdk8s synth` command is a convenience command which will simply execute 4 | the application defined in `cdk8s.yaml` under `app`. 5 | 6 | For example, if your `cdk8s.yaml` file looks like this: 7 | 8 | ```yaml 9 | app: node app.js 10 | ``` 11 | 12 | Then, `cdk8s synth` will execute `node app.js`. 13 | 14 | ## Configuring synth output 15 | 16 | The properties of the synthesized YAML from `cdk8s synth` can be modified by the properties of the `App` construct. 17 | Things like file extensions, how API objects are distributed between files, and the output directory can all 18 | be configured in your [`AppProps`](https://github.com/cdk8s-team/cdk8s-core/blob/2.x/docs/typescript.md#appprops-) 19 | 20 | For example: 21 | 22 | ```typescript 23 | const app = new App({ 24 | // Instead of the default "dist" 25 | outdir: "output", 26 | // Instead of ".k8s.yaml" 27 | outputFileExtension: ".generated.yaml", 28 | // Divide every resource into its own file, instead of grouping by Chart 29 | yamlOutputType: YamlOutputType.FILE_PER_RESOURCE, 30 | }); 31 | ``` 32 | 33 | ## Validating Manifests 34 | 35 | You can perform validation on the manifests produced by cdk8s by configuring third-party validation 36 | plugins. To do so, use the `validations` property in the `cdk8s.yaml` configuration file: 37 | 38 | ```yaml 39 | language: typescript 40 | app: ts-node main.ts 41 | validations: 42 | - package: '@datreeio/datree-cdk8s' 43 | class: DatreeValidation 44 | version: 1.3.4 45 | ``` 46 | 47 | With this configuration, `cdk8s` will dynamically install the `@datreeio/datree-cdk8s` package from NPM during 48 | synthesis, and produce a violation report. For example: 49 | 50 | ```console 51 | Validation Report (@datreeio/datree-cdk8s@1.3.4) 52 | ------------------------------------------------ 53 | 54 | (Summary) 55 | 56 | ╔═══════════╤════════════════════════╗ 57 | ║ Status │ failure ║ 58 | ╟───────────┼────────────────────────╢ 59 | ║ Plugin │ @datreeio/datree-cdk8s ║ 60 | ╟───────────┼────────────────────────╢ 61 | ║ Version │ 1.3.4 ║ 62 | ╟───────────┼────────────────────────╢ 63 | ║ Customize │ https://app.datree.io ║ 64 | ║ policy │ ║ 65 | ╚═══════════╧════════════════════════╝ 66 | 67 | 68 | (Violations) 69 | 70 | Ensure each container image has a pinned (tag) version (2 occurrences) 71 | 72 | Occurrences: 73 | 74 | - Construct Path: cdk8s-app/Web/Resource 75 | - Manifest Path: ./dist/cdk8s-app.k8s.yaml 76 | - Resource Name: cdk8s-app-web-c825557e 77 | - Locations: 78 | > spec/template/spec/containers/0/image (line: 31:18) 79 | 80 | - Construct Path: cdk8s-app/Cache/Resource 81 | - Manifest Path: ./dist/cdk8s-app.k8s.yaml 82 | - Resource Name: cdk8s-app-cache-c8fee821 83 | - Locations: 84 | > spec/template/spec/containers/0/image (line: 112:18) 85 | 86 | Recommendation: Incorrect value for key `image` - specify an image version to avoid unpleasant "version surprises" in the future 87 | How to fix: https://hub.datree.io/ensure-image-pinned-version 88 | 89 | Validation failed. See above reports for details 90 | ``` 91 | 92 | If the report resulted in a failure, the `cdk8s synth` command will fail. 93 | You can also put the contents of the `validation` property into a separate file (either remote or local), 94 | and refer to it: 95 | 96 | ```yaml 97 | language: typescript 98 | app: ts-node main.ts 99 | validations: http://path/to/validations.yaml 100 | ``` 101 | 102 | ### Private Validation Plugins 103 | 104 | To use a validation plugin that is hosted in a private NPM registry, use the `installEnv` 105 | property to specify a custom registry: 106 | 107 | ```yaml 108 | language: typescript 109 | app: ts-node main.ts 110 | validations: 111 | - package: my-private-plugin 112 | class: MyValidation 113 | version: 0.0.1 114 | installEnv: 115 | npm_config_registry: http://my/custom/registry 116 | ``` 117 | 118 | > All key value pairs in the `installEnv` property will be passed as is to the `npm` command that `cdk8s` 119 | > executes when it installs your plugin. 120 | 121 | ### Pre-Installing Plugins 122 | 123 | You can prevent `cdk8s` from contacting NPM during synthesis by providing it with the necessary plugins. 124 | Plugins are stored in the `~/.cdk8s/plugins` directory, and `cdk8s` will first check if a plugin 125 | is already installed before trying to install it. 126 | 127 | If you pre-populate the plugins directory correctly, you can prevent `cdk8s` from contacting NPM. 128 | This can be useful for air-gapped synthesis scenarios for example. 129 | 130 | Here is how `cdk8s` expects the directory to be structured, assuming the plugin package is called `plugin1`, and its version is `0.0.1` 131 | 132 | `~/.cdk8s/plugins/plugin1/0.0.1/node_modules/plugin1/package.json` 133 | 134 | You can achieve this structure by running the following commands: 135 | 136 | ```console 137 | mkdir -p ~/.cdk8s/plugins/plugin1/0.0.1/node_modules/plugin1 138 | npm install --prefix ~/.cdk8s/plugins/plugin1/0.0.1/node_modules/plugin1 plugin1@0.0.1 139 | ``` 140 | 141 | You can also control the plugins storage directory by one of: 142 | 143 | - `--plugins-dir` in the `cdk8s synth` command. 144 | - `CDK8S_PLUGINS_DIR` environment variable. 145 | - `pluginsDirectory` key in the `cdk8s.yaml` configuration file. 146 | 147 | ### Available Plugins 148 | 149 | - [Datree](https://github.com/datreeio/datree-cdk8s) 150 | 151 | ### Writing Plugins 152 | 153 | See [cdk8s-validation-plugin-example](https://github.com/cdk8s-team/cdk8s-validation-plugin-example) 154 | 155 | ## Helm Synthesis 156 | 157 | You can synthesize your cdk8s application to a format that is compatible with [helm](https://helm.sh/). 158 | 159 | For example, you can run: 160 | 161 | ``` 162 | cdk8s synth --format helm --chart-version 1.0.0 163 | ``` 164 | 165 | Then it will synthesize a generated helm chart to the output folder (default is 'dist'). The `--chart-version` will be the [version](https://helm.sh/docs/topics/charts/#charts-and-versioning) of the helm chart and must follow [SemVer2](https://semver.org/spec/v2.0.0.html) standards. The synthesized manifests will be placed in `templates/` folder. And, if any crds were mentioned in `cdk8s.yaml` config file as `imports`, then they will be downloaded and placed in the `crds/` folder. 166 | 167 | The folder structure will look like: 168 | 169 | ``` 170 | dist/ 171 | ├── Chart.yaml 172 | ├── README.md 173 | ├── crds/ 174 | └── templates/ 175 | ``` 176 | 177 | !!! note 178 | CRDs are not supported when `--chart-api-version` is set to `v1`. 179 | 180 | You can use the synthesized chart to deploy using helm: 181 | 182 | ``` 183 | cdk8s synth --format helm --chart-version 1.0.0 && helm install ./dist 184 | ``` 185 | 186 | !!! note 187 | Templates within the generated Helm chart are pure and static Kubernetes manifests; they don't contain any helm template directives. This means they cannot be customized with a values.yaml file or the release name. One important implication of this is that you cannot deploy two different releases of the same chart, as resource names will collide. If you need customization, you can do this within the cdk8s application (for example by explicitly reading a values.yaml file). -------------------------------------------------------------------------------- /docs/ecosystem-interoperability.md: -------------------------------------------------------------------------------- 1 | # Ecosystem Interoperability 2 | 3 | As we know, there are many [CDK based libraries](http://constructs.dev/) out there, and you might want to incorporate cdk8s along side other libraries in the same application. 4 | 5 | !!! example 6 | 7 | For example, you can use cdk8s to define charts in an AWS CDK application, and [apply them using the EKS construct library](https://docs.aws.amazon.com/cdk/api/v1/docs/aws-eks-readme.html#cdk8s-charts). 8 | 9 | This ability, or interoperability, is based on the [constructs programming model](https://www.npmjs.com/package/constructs), which is the underlying technology on which all CDK libraries are built upon. All CDK libraries participating in the same application, must use the same major version of [constructs](https://www.npmjs.com/package/constructs), which currently has both a `3.x` and a `10.x` major version lines. 10 | 11 | In order to incorporate `cdk8s` in applications that use either version line, we need to maintain two major versions of `cdk8s`, one for each version of `constructs`. 12 | 13 | - Version `1.x` can be used along side libraries that depend on `constructs` version 3.x. 14 | 15 | > For example: [AWS CDK v1](https://constructs.dev/search?q=aws-cdk&cdk=aws-cdk&cdkver=1&offset=0). 16 | 17 | - Version `2.x` can be used along side libraries that depend on `constructs` version 10.x. 18 | 19 | > For example: [AWS CDK v2](https://constructs.dev/search?q=aws-cdk&cdk=aws-cdk&cdkver=2&offset=0). 20 | -------------------------------------------------------------------------------- /docs/examples/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - index.md 3 | -------------------------------------------------------------------------------- /docs/examples/index.md: -------------------------------------------------------------------------------- 1 | # Examples 2 | 3 | This section includes references for cdk8s and cdk8s+ examples that we have in our GitHub repository. 4 | 5 | === "TypeScript" 6 | 7 | * [Hello, Kubernetes!](https://github.com/cdk8s-team/cdk8s-examples/tree/main/typescript/cdk8s-core) - Deploys [hello-kubernetes](https://github.com/paulbouwer/hello-kubernetes) as a Service behind a LoadBalancer. 8 | * [CRDs](https://github.com/cdk8s-team/cdk8s-examples/tree/main/typescript/cdk8s-crd) - Shows how to import and use [Custom Resource Definitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) 9 | * [Elasticsearch (cdk8s+)](https://github.com/cdk8s-team/cdk8s-examples/tree/main/typescript/cdk8s-plus-elasticsearch-query) - Creating a query service on top of Elasticsearch with cdk8s+ 10 | * [Ingress (cdk8s+)](https://github.com/cdk8s-team/cdk8s-examples/tree/main/typescript/cdk8s-plus-http-echo) - Example of using cdk8s+ `Ingress` resource. 11 | * [Podinfo](https://github.com/cdk8s-team/cdk8s-examples/tree/main/typescript/cdk8s-plus-pod-info) - Exploration of high-level APIs for **Deployment**, **Service**, **AutoScaler** and **Ingress** based on the [podinfo project](https://hub.docker.com/r/stefanprodan/podinfo). 12 | * [WebService Abstraction](https://github.com/cdk8s-team/cdk8s-examples/tree/main/typescript/cdk8s-composition) - Demonstrates how to make your first high-level construct which represents a web service which abstracts the `hello` example from earlier into a reusable piece of infrastructure. 13 | * [WebCacheDB (cdk8s+)](https://github.com/cdk8s-team/cdk8s-examples/tree/main/typescript/cdk8s-plus-web-cache-db) - A demonstration of cdk8s-plus capabilities for authoring complex Kubernetes applications. 14 | 15 | === "Python" 16 | 17 | * [Hello, Kubernetes!](https://github.com/cdk8s-team/cdk8s-examples/tree/main/python/cdk8s-core) - Deploys [hello-kubernetes](https://github.com/paulbouwer/hello-kubernetes) as a Service behind a LoadBalancer. 18 | * [CRDs](https://github.com/cdk8s-team/cdk8s-examples/tree/main/python/cdk8s-crd) - Shows how to import and use [Custom Resource Definitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) 19 | * [WebService Abstraction](https://github.com/cdk8s-team/cdk8s-examples/tree/main/python/cdk8s-composition) - Demonstrates how to make your first high-level construct which represents a web service which abstracts the `hello` example from earlier into a reusable piece of infrastructure. 20 | 21 | === "Java" 22 | 23 | * [Hello, Kubernetes!](https://github.com/cdk8s-team/cdk8s-examples/tree/main/java/cdk8s-core) - Deploys [hello-kubernetes](https://github.com/paulbouwer/hello-kubernetes) as a Service behind a LoadBalancer. 24 | * [CRDs](https://github.com/cdk8s-team/cdk8s-examples/tree/main/java/cdk8s-crd) - Shows how to import and use [Custom Resource Definitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) 25 | * [WebService Abstraction](https://github.com/cdk8s-team/cdk8s-examples/tree/main/java/cdk8s-composition) - Demonstrates how to make your first high-level construct which represents a web service which abstracts the `hello` example from earlier into a reusable piece of infrastructure. 26 | 27 | === "Go" 28 | 29 | * [Hello, Kubernetes!](https://github.com/cdk8s-team/cdk8s-examples/tree/main/go/cdk8s-core) - Deploys [hello-kubernetes](https://github.com/paulbouwer/hello-kubernetes) as a Service behind a LoadBalancer. 30 | * [CRDs](https://github.com/cdk8s-team/cdk8s-examples/tree/main/go/cdk8s-crd) - Shows how to import and use [Custom Resource Definitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) 31 | * [WebService Abstraction](https://github.com/cdk8s-team/cdk8s-examples/tree/main/go/cdk8s-composition) - Demonstrates how to make your first high-level construct which represents a web service which abstracts the `hello` example from earlier into a reusable piece of infrastructure. 32 | 33 | !!! info 34 | We try to maintain the same set of examples in all supported languages. 35 | **[Help us!](../CONTRIBUTING.md)** 36 | -------------------------------------------------------------------------------- /docs/get-started/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - index.md 3 | - Python: python.md 4 | - TypeScript: typescript.md 5 | - Java: java.md 6 | - Go: go.md -------------------------------------------------------------------------------- /docs/get-started/go.md: -------------------------------------------------------------------------------- 1 | # Getting started with cdk8s for Go 2 | In this guide, we'll walk you through the process of building a basic Kubernetes application using cdk8s for Go. 3 | 4 | ## Prerequisites 5 | 1. To install the cdk8s CLI, you need the [Node Package Manager (npm)](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) installed on your local machine. 6 | 2. cdk8s for Go supports Go versions 1.16+. Check your Go version: 7 | ```bash 8 | go version 9 | ``` 10 | 11 | ## Set up an environment 12 | ### Install the CLI 13 | To initialize a cdk8s project and auto-generate Kubernetes manifests based on our code, we need the cdk8s CLI: 14 | 15 | 1. Run the following command to install the CLI using [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). For more installation methods, see [Install the cdk8s CLI](./../cli/installation.md). 16 | ```console 17 | npm install -g cdk8s-cli 18 | ``` 19 | 20 | ### Create a project 21 | Next, we’ll initialize a project to create the directory structure and install the necessary dependencies using the [init](./../cli/init.md) command. 22 | 23 | 1. In a terminal window, create a new directory: 24 | ```bash 25 | mkdir cdk8s-golang 26 | ``` 27 | 28 | 2. Next, run the following command inside the `cdk8s-golang` directory: 29 | ```console 30 | cdk8s init go-app 31 | ``` 32 | 33 | 3. In your preferred code editor, open the `main.go` file. 34 | ```go 35 | package main 36 | 37 | import ( 38 | "github.com/aws/constructs-go/constructs/v10" 39 | "github.com/aws/jsii-runtime-go" 40 | "github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2" 41 | ) 42 | 43 | type MyChartProps struct { 44 | cdk8s.ChartProps 45 | } 46 | 47 | func NewMyChart(scope constructs.Construct, id string, props *MyChartProps) cdk8s.Chart { 48 | var cprops cdk8s.ChartProps 49 | if props != nil { 50 | cprops = props.ChartProps 51 | } 52 | chart := cdk8s.NewChart(scope, jsii.String(id), &cprops) 53 | 54 | // define resources here 55 | 56 | return chart 57 | } 58 | 59 | func main() { 60 | app := cdk8s.NewApp(nil) 61 | NewMyChart(app, "cdk8s-golang", nil) 62 | app.Synth() 63 | } 64 | ``` 65 | 66 | This sample shows the basic structure of a cdk8s application with the essential libraries: **constructs** and **cdk8s**. These libraries supply the foundational classes and methods required for working with cdk8s. It includes the following components: 67 | 68 | * A `NewMyChart` function that creates a specific instance of a [Chart](https://pkg.go.dev/github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2#Chart). It is responsible for initializing the Chart instance and registering the Kubernetes resources to it. 69 | * A `main` function acting as the primary entry point of the cdk8s application. It instantiates the [App](https://pkg.go.dev/github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2#App) instance, which oversees the application's lifecycle and resources. 70 | * The function `NewMyChart` is called by passing the app instance and a string identifier, "go", as arguments. This action generates and registers the chart and all its resources to the app. Note that in this example, the "cdk8s-golang" string identifier is autogenerated based on the current directory name. 71 | * The `Synth` method is called on the `app` instance, which produces the required Kubernetes YAML manifest files based on the defined resources. Note that in this example, we haven't defined any resources within the `NewMyChart` function, so running the "cdk8s synth" command in the CLI would generate a blank Kubernetes manifest. 72 | 73 | ## Define Kubernetes resources 74 | Now, let's delve into defining Kubernetes resources for our application. In this example, we'll outline a basic Kubernetes [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) for a sample app. We'll start by importing the `imports` directory and the `k8s` sub-directory, which houses all cdk8s Kubernetes classes and functions. 75 | 76 | ### Copy the code sample 77 | 78 | 1. Copy and paste the following code sample into the existing `main.go` file of your project. 79 | 80 | ```go 81 | package main 82 | 83 | import ( 84 | "example.com/cdk8s-golang/imports/k8s" 85 | "github.com/aws/constructs-go/constructs/v10" 86 | "github.com/aws/jsii-runtime-go" 87 | "github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2" 88 | ) 89 | 90 | func NewChart(scope constructs.Construct, id string, ns string, appLabel string) cdk8s.Chart { 91 | 92 | chart := cdk8s.NewChart(scope, jsii.String(id), &cdk8s.ChartProps{ 93 | Namespace: jsii.String(ns), 94 | }) 95 | 96 | labels := map[string]*string{ 97 | "app": jsii.String(appLabel), 98 | } 99 | 100 | k8s.NewKubeDeployment(chart, jsii.String("deployment"), &k8s.KubeDeploymentProps{ 101 | Spec: &k8s.DeploymentSpec{ 102 | Replicas: jsii.Number(3), 103 | Selector: &k8s.LabelSelector{ 104 | MatchLabels: &labels, 105 | }, 106 | Template: &k8s.PodTemplateSpec{ 107 | Metadata: &k8s.ObjectMeta{ 108 | Labels: &labels, 109 | }, 110 | Spec: &k8s.PodSpec{ 111 | Containers: &[]*k8s.Container{{ 112 | Name: jsii.String("app-container"), 113 | Image: jsii.String("nginx:1.19.10"), 114 | Ports: &[]*k8s.ContainerPort{{ 115 | ContainerPort: jsii.Number(80), 116 | }}, 117 | }}, 118 | }, 119 | }, 120 | }, 121 | }) 122 | 123 | return chart 124 | } 125 | 126 | func main() { 127 | app := cdk8s.NewApp(nil) 128 | 129 | NewChart(app, "getting-started", "default", "my-app") 130 | 131 | app.Synth() 132 | } 133 | ``` 134 | 135 | A few things worth noting about this sample: 136 | 137 | - The `NewChart` function utilizes Go's strong typing and interface-based design to construct a Kubernetes Deployment. This Deployment is set up with specific parameters like replica count, label selectors, and pod specifications. This method takes advantage of Go's map data structures to dynamically assign the "app" key in label selectors and metadata labels, offering a straightforward and efficient way to configure essential details. 138 | 139 | ## Generate Kubernetes manifests 140 | After you have defined the Kubernetes resources for your application, you are ready to generate the Kubernetes manifest that will define your Deployment resource. 141 | 142 | ### Run the synth command 143 | 1. Open a terminal and navigate to your project directory. 144 | 2. Run the [synth](https://cdk8s.io/docs/latest/cli/synth/) command. This command generates a Kubernetes manifest file in the `dist` folder of your project directory. The manifest file contains all the resources you defined inside the `MyChart` class. 145 | ```console 146 | cdk8s synth 147 | ``` 148 | 149 | ### View the manifest 150 | 1. Open the `dist/getting-started.k8s.yaml` file. You should see a Kubernetes manifest similar to the following: 151 | ```bash 152 | apiVersion: apps/v1 153 | kind: Deployment 154 | metadata: 155 | name: getting-started-deployment-c80c7257 156 | namespace: default 157 | spec: 158 | replicas: 3 159 | selector: 160 | matchLabels: 161 | app: my-app 162 | template: 163 | metadata: 164 | labels: 165 | app: my-app 166 | spec: 167 | containers: 168 | - image: nginx:1.19.10 169 | name: app-container 170 | ports: 171 | - containerPort: 80 172 | ``` 173 | ## Conclusion 174 | Throughout this guide, we introduced you to the cdk8s Go library and guided you through the process of creating a cdk8s Go application. We initiated a simple project and constructed a Kubernetes Deployment using cdk8s code. This included leveraging Go-specific programming language conventions to dynamically set the "app" key in "label" selectors and "metadata" labels for Kubernetes resources using Go's versatile handling of map data structures. 175 | 176 | ## Next up 177 | - To run a complete code sample, we recommend diving into the Kubernetes [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) and [Service](https://kubernetes.io/docs/concepts/services-networking/service/) using the [cdk8s-core](https://github.com/cdk8s-team/cdk8s-examples/blob/main/go/cdk8s-core/main.go) sample application. 178 | -------------------------------------------------------------------------------- /docs/get-started/index.md: -------------------------------------------------------------------------------- 1 | # Getting started 2 | CDK8s streamlines the automation of deployment, versioning, and configuration for your Kubernetes resources, so you can build and upgrade your clusters more easily. Whether you're creating new applications, managing microservices, or working with data processing pipelines, cdk8s has you covered. To kick start your journey, choose one of our language guides tailored to your preferred programming language. 3 | 4 | ### Choose a language guide 5 | - [Python](python.md) 6 | - [Typescript](typescript.md) 7 | - [Java](java.md) 8 | - [Go](go.md) 9 | -------------------------------------------------------------------------------- /docs/get-started/python.md: -------------------------------------------------------------------------------- 1 | # Getting started with cdk8s for Python 2 | In this guide, we'll walk you through the most essential concepts you need to know in order to build a Kubernetes application using cdk8s for Python. 3 | 4 | ## Prerequisites 5 | 1. To install the cdk8s CLI, you need the [Node Package Manager (npm)](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) installed on your local machine. 6 | 2. cdk8s for Python supports Python versions 3.7+. Check your Python version: 7 | ```bash 8 | python3 --version 9 | ``` 10 | 11 | ## Set up an environment 12 | ### Initial setup 13 | To get setup, follow these general steps: 14 | 15 | 1. To begin, you’ll need pipenv 2018.11.26+ installed. If you’re not familiar with this setup, use these instructions to [setup pipenv](https://pipenv.pypa.io/en/latest/install/). 16 | 17 | ### Install the CLI 18 | To initialize a cdk8s project and auto-generate Kubernetes manifests based on our code, we need the cdk8s CLI: 19 | 20 | 1. Run the following command to install the CLI using [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). For more installation methods, see [Install the cdk8s CLI](./../cli/installation.md). 21 | ```console 22 | npm install -g cdk8s-cli 23 | ``` 24 | 25 | ### Create a project 26 | Next, we’ll initialize a project to create the directory structure and install the necessary dependencies using the [init](./../cli/init.md) command. 27 | 28 | 1. In a terminal window, run the following command in an empty directory: 29 | ```console 30 | cdk8s init python-app 31 | ``` 32 | 33 | 1. In your preferred code editor, open the `main.py` file. 34 | ```python 35 | #!/usr/bin/env python 36 | from constructs import Construct 37 | from cdk8s import App, Chart 38 | 39 | 40 | class MyChart(Chart): 41 | def __init__(self, scope: Construct, id: str): 42 | super().__init__(scope, id) 43 | 44 | # define resources here 45 | 46 | 47 | app = App() 48 | MyChart(app, "python") 49 | 50 | app.synth() 51 | ``` 52 | 53 | This sample shows the basic structure of a cdk8s application with the essential libraries: **constructs** and **cdk8s**. These libraries supply the foundational classes and methods required for working with cdk8s. It includes the following components: 54 | 55 | * A custom `MyChart` class inherits from the [Chart](https://cdk8s.io/docs/latest/reference/cdk8s/python/#chart) base class provided by the cdk8s library, serving as a representation of the Kubernetes resources to be generated and managed. 56 | * The `__init__` method within the `MyChart` class is responsible for initializing the base class ([Chart](https://cdk8s.io/docs/latest/reference/cdk8s/python/#chart)) and specifying the Kubernetes resources. This method is invoked when creating an instance of the class. 57 | * An instance of the [App](https://cdk8s.io/docs/latest/reference/cdk8s/python/#app) class signifies the primary entry point of the cdk8s application and oversees the application's lifecycle and resources. 58 | * An instance of the `MyChart` class is created by passing the app instance and a string identifier, "python", as arguments. This action generates and registers the Kubernetes resources defined in the `MyChart` class within the application. Note that in this example, the "python" string identifier is autogenerated based on the current directory name. 59 | * The `synth` method is called on the `app` instance, which produces the required Kubernetes YAML manifest files based on the defined resources. Note that in this example, we haven't defined any resources within the `MyChart` constructor, so running the "cdk8s synth" command in the CLI would generate a blank Kubernetes manifest. 60 | 61 | ## Define Kubernetes resources 62 | Now, we are ready to define Kubernetes resources for our application. In this sample, we define a basic Kubernetes [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) for a sample application. We start by importing the imports directory and the **k8s** sub-directory, which contains an `__init__.py` file where all cdk8s Kubernetes classes and functions are defined. 63 | 64 | ### Copy the code sample 65 | 1. Copy and paste the following code sample into the existing `main.py` file of your project. 66 | ```python 67 | #!/usr/bin/env python 68 | from cdk8s import App, Chart 69 | from constructs import Construct 70 | from imports import k8s 71 | 72 | 73 | class MyChart(Chart): 74 | def __init__(self, scope: Construct, ns: str, app_label: str): 75 | super().__init__(scope, ns) 76 | 77 | # Define a Kubernetes Deployment 78 | k8s.KubeDeployment(self, "my-deployment", 79 | spec=k8s.DeploymentSpec( 80 | replicas=3, 81 | selector=k8s.LabelSelector(match_labels={"app": app_label}), 82 | template=k8s.PodTemplateSpec( 83 | metadata=k8s.ObjectMeta(labels={"app": app_label}), 84 | spec=k8s.PodSpec(containers=[ 85 | k8s.Container( 86 | name="app-container", 87 | image="nginx:1.19.10", # Using public nginx image 88 | ports=[k8s.ContainerPort(container_port=80)] # Nginx listens on port 80 by default 89 | ) 90 | ]) 91 | ) 92 | ) 93 | ) 94 | 95 | app = App() 96 | MyChart(app, "getting-started", app_label="my-app") 97 | 98 | app.synth() 99 | ``` 100 | 101 | A few things worth noting about this sample: 102 | 103 | - The `__init__` method in the custom `MyChart` class uses idiomatic Python's features to construct a Kubernetes Deployment. The Deployment is created with specific parameters including replica count, label selectors, and pod specifications. Just as in the custom `MyChart` class instantiation process, this approach utilizes Python's flexible handling of dictionary data structures to dynamically assign the "app" key in label selectors and metadata labels for our Kubernetes resources, creating a clear and concise way to set key configuration details. 104 | 105 | ## Generate Kubernetes manifests 106 | After you have defined the Kubernetes resources for your application, you are ready to generate the Kubernetes manifest that will define your Deployment resource. 107 | 108 | ### Run the synth command 109 | 1. Open a terminal and navigate to your project directory. 110 | 2. Run the [synth](https://cdk8s.io/docs/latest/cli/synth/) command. This command generates a Kubernetes manifest file in the `dist` folder of your project directory. The manifest file contains all the resources you defined inside the `MyChart` class. 111 | ```console 112 | cdk8s synth 113 | ``` 114 | 115 | ### View the manifest 116 | 1. Open the `dist/getting-started.k8s.yaml` file. You should see a Kubernetes manifest similar to the following: 117 | ```yaml 118 | apiVersion: apps/v1 119 | kind: Deployment 120 | metadata: 121 | name: getting-started-my-deployment-c85252a6 122 | spec: 123 | replicas: 3 124 | selector: 125 | matchLabels: 126 | app: my-app 127 | template: 128 | metadata: 129 | labels: 130 | app: my-app 131 | spec: 132 | containers: 133 | - image: nginx:1.19.10 134 | name: app-container 135 | ports: 136 | - containerPort: 80 137 | ``` 138 | 139 | ## Conclusion 140 | Throughout this guide, we introduced you to the cdk8s Python library and guided you through the process of creating a cdk8s Python application. We initiated a simple project and constructed a Kubernetes Deployment using cdk8s code. This included leveraging Python-specific programming language conventions to dynamically set the "app" key in "label" selectors and "metadata" labels for Kubernetes resources using Python's versatile handling of dictionary data structures. 141 | 142 | ## Next up 143 | - To run a complete code sample, we recommend diving into the Kubernetes [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) and [Service](https://kubernetes.io/docs/concepts/services-networking/service/) using the [cdk8s-core](https://github.com/cdk8s-team/cdk8s-examples/blob/main/python/cdk8s-core/main.py) sample application. 144 | 145 | -------------------------------------------------------------------------------- /docs/get-started/typescript.md: -------------------------------------------------------------------------------- 1 | # Getting started with cdk8s for Typescript 2 | In this guide, we'll walk you through the most essential concepts you need to know in order to build a Kubernetes application using cdk8s for Typescript. 3 | 4 | ## Prerequisites 5 | 1. To install the cdk8s CLI, you need the [Node Package Manager (npm)](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) installed on your local machine. 6 | 2. cdk8s for Typescript supports Node.js versions 16.20.0+. Check your Node.js version: 7 | ```bash 8 | node --version 9 | ``` 10 | 11 | ## Set up an environment 12 | ### Install the CLI 13 | To initialize a cdk8s project and auto-generate Kubernetes manifests based on our code, we need the cdk8s CLI: 14 | 15 | 1. Run the following command to install the CLI using [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). For more installation methods, see [Install the cdk8s CLI](./../cli/installation.md). 16 | ```console 17 | npm install -g cdk8s-cli 18 | ``` 19 | 20 | ### Create a project 21 | Next, we’ll initialize a project to create the directory structure and install the necessary dependencies using the [init](./../cli/init.md) command. 22 | 23 | 1. In a terminal window, run the following command in an empty directory: 24 | ```console 25 | cdk8s init typescript-app 26 | ``` 27 | 28 | 1. In your preferred code editor, open the `main.ts` file. 29 | ```typescript 30 | import { Construct } from 'constructs'; 31 | import { App, Chart, ChartProps } from 'cdk8s'; 32 | 33 | export class MyChart extends Chart { 34 | constructor(scope: Construct, id: string, props: ChartProps = { }) { 35 | super(scope, id, props); 36 | 37 | // define resources here 38 | 39 | } 40 | } 41 | 42 | const app = new App(); 43 | new MyChart(app, 'typescript'); 44 | app.synth(); 45 | ``` 46 | 47 | This sample shows the basic structure of a cdk8s application with the essential libraries: **constructs** and **cdk8s**. These libraries supply the foundational classes and methods required for working with cdk8s. It includes the following components: 48 | 49 | * A custom `MyChart` class inherits from the [Chart](https://cdk8s.io/docs/latest/reference/cdk8s/typescript/#chart) base class provided by the cdk8s library, serving as a representation of the Kubernetes resources to be generated and managed. 50 | * The `constructor` method within the MyChart class is responsible for initializing the base class ([Chart](https://cdk8s.io/docs/latest/reference/cdk8s/typescript/#chart)) and specifying the Kubernetes resources. This method is invoked when creating an instance of the class. 51 | * An instance of the [App](https://cdk8s.io/docs/latest/reference/cdk8s/typescript/#app) class signifies the primary entry point of the cdk8s application and oversees the application's lifecycle and resources. 52 | * An instance of the `MyChart` class is created by passing the app instance and a string identifier, "typescript", as arguments. This action generates and registers the Kubernetes resources defined in the `MyChart` class within the application. Note that in this example, the "typescript" string identifier is autogenerated based on the current directory name. 53 | * The `synth` method is called on the `app` instance, which produces the required Kubernetes YAML manifest files based on the defined resources. Note that in this example, we haven't defined any resources within the `MyChart` constructor, so running the "cdk8s synth" command in the CLI would generate a blank Kubernetes manifest. 54 | 55 | ## Define Kubernetes resources 56 | Now, let's delve into defining Kubernetes resources for our application. In this example, we'll outline a basic Kubernetes [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) for a sample app. We'll start by importing the `imports` directory and the `k8s` sub-directory, which houses the `index.ts` file containing all cdk8s Kubernetes classes and functions. 57 | ### Copy the code sample 58 | 1. Copy and paste the following code sample into the existing `main.ts` file of your project. 59 | ```typescript 60 | import { Construct } from 'constructs'; 61 | import { App, Chart } from 'cdk8s'; 62 | import { KubeDeployment } from './imports/k8s'; 63 | 64 | class MyChart extends Chart { 65 | constructor(scope: Construct, ns: string, appLabel: string) { 66 | super(scope, ns); 67 | 68 | // Define a Kubernetes Deployment 69 | new KubeDeployment(this, 'my-deployment', { 70 | spec: { 71 | replicas: 3, 72 | selector: { matchLabels: { app: appLabel } }, 73 | template: { 74 | metadata: { labels: { app: appLabel } }, 75 | spec: { 76 | containers: [ 77 | { 78 | name: 'app-container', 79 | image: 'nginx:1.19.10', 80 | ports: [{ containerPort: 80 }] 81 | } 82 | ] 83 | } 84 | } 85 | } 86 | }); 87 | } 88 | } 89 | 90 | const app = new App(); 91 | new MyChart(app, 'getting-started', 'my-app'); 92 | 93 | app.synth(); 94 | ``` 95 | 96 | A few things worth noting about this sample: 97 | 98 | - The `constructor` method in the custom `MyChart` class employs TypeScript's type system to construct a Kubernetes Deployment. This Deployment is configured with specific parameters, such as replica count, label selectors, and pod specifications. This approach leverages TypeScript's type system to dynamically assign the "app" key in label selectors and metadata labels, creating a clear and concise way to set key configuration details. 99 | 100 | ## Generate Kubernetes manifests 101 | After you have defined the Kubernetes resources for your application, you are ready to generate the Kubernetes manifest that will define your Deployment resource. 102 | 103 | ### Run the synth command 104 | 1. Open a terminal and navigate to your project directory. 105 | 2. Run the [synth](https://cdk8s.io/docs/latest/cli/synth/) command. This command generates a Kubernetes manifest file in the `dist` folder of your project directory. The manifest file contains all the resources you defined inside the `MyChart` class. 106 | ```console 107 | cdk8s synth 108 | ``` 109 | 110 | ### View the manifest 111 | 1. Open the `dist/getting-started.k8s.yaml` file. You should see a Kubernetes manifest similar to the following: 112 | ```yaml 113 | apiVersion: apps/v1 114 | kind: Deployment 115 | metadata: 116 | name: getting-started-my-deployment-c85252a6 117 | spec: 118 | replicas: 3 119 | selector: 120 | matchLabels: 121 | app: my-app 122 | template: 123 | metadata: 124 | labels: 125 | app: my-app 126 | spec: 127 | containers: 128 | - image: nginx:1.19.10 129 | name: app-container 130 | ports: 131 | - containerPort: 80 132 | ``` 133 | 134 | ## Conclusion 135 | Throughout this guide, we introduced you to the cdk8s Typescript library and guided you through the process of creating a cdk8s Typescript application. We've initiated a simple project and crafted a Kubernetes Deployment using cdk8s code. This involved utilizing TypeScript's strong type system to dynamically set the "app" key in label selectors and metadata labels for Kubernetes resources. 136 | 137 | ## Next up 138 | - To run a complete code sample, we recommend diving into the Kubernetes [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) and [Service](https://kubernetes.io/docs/concepts/services-networking/service/) using the [cdk8s-core](https://github.com/cdk8s-team/cdk8s-examples/blob/main/typescript/cdk8s-core/index.ts) sample application. 139 | 140 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | # What is cdk8s? 2 | 3 | **cdk8s** is a software development framework for defining Kubernetes 4 | applications and reusable abstractions using familiar programming languages and 5 | rich object-oriented APIs. cdk8s generates pure Kubernetes YAML - you can use 6 | cdk8s to define applications for any Kubernetes cluster running anywhere. 7 | 8 | !!! info 9 | 10 | The documentation here relates to version `2.x` of the cdk8s toolchain, which is the latest. If you are still using version `1.x`, please refer to the [Migrating from 1.x Guide](./migrating-from-1.x.md). 11 | 12 | ![demo](./assets/animation.gif) 13 | 14 | Read [our blog](https://aws.amazon.com/blogs/containers/introducing-cdk-for-kubernetes/) or [watch our CNCF webinar](https://www.cncf.io/webinars/end-yaml-engineering-with-cdk8s/) to learn more and see a live demo of cdk8s in action. 15 | 16 | ## How does it work? 17 | 18 | **cdk8s** apps are programs written in one of the supported programming 19 | languages. They are structured as a tree of 20 | [constructs](https://github.com/aws/constructs). 21 | 22 | The root of the tree is an `App` construct. Within an app, users define any 23 | number of charts (classes that extend the `Chart` class). Each chart is 24 | synthesized into a separate Kubernetes manifest file. Charts are, in turn, 25 | composed of any number of constructs, and eventually from resources, which 26 | represent any Kubernetes resource, such as `Pod`, `Service`, `Deployment`, 27 | `ReplicaSet`, etc. 28 | 29 | cdk8s apps only ***define*** Kubernetes applications, they don't actually apply 30 | them to the cluster. When an app is executed, it *synthesizes* all the charts 31 | defined within the app into the `dist` directory, and then those charts can be 32 | applied to any Kubernetes cluster using `kubectl apply -f dist/chart.k8s.yaml` or a GitOps tool like [Flux](https://fluxcd.io/). 33 | 34 | > **cdk8s** is based on the design concepts and technologies behind the [AWS 35 | Cloud Development Kit](https://aws.amazon.com/cdk), and can interoperate with 36 | AWS CDK constructs to define cloud-native applications that include both 37 | Kubernetes resources and other CDK constructs as first class citizens. 38 | -------------------------------------------------------------------------------- /docs/landing-page-1900x1200.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/docs/landing-page-1900x1200.png -------------------------------------------------------------------------------- /docs/media.md: -------------------------------------------------------------------------------- 1 | # Media 2 | 3 | ## Logos 4 | 5 | ### Horizontal 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 |
PNGSVG
color
black
white
36 | 37 | ### Stacked 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 |
PNGSVG
color
black
white
68 | 69 | ### Icon 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 |
PNGSVG
color
black
white
100 | -------------------------------------------------------------------------------- /docs/migrating-from-1.x.md: -------------------------------------------------------------------------------- 1 | # Migrating from 1.x 2 | 3 | This page describes the difference between versions `1.x` and `2.x` of the cdk8s toolchain, as well as instructions on how to migrate from one to the other. 4 | 5 | ## Deprecation Timeline 6 | 7 | Version `1.x` of the cdk8s toolchain will be deprecated on 01/01/2023. After which, it will only receive critical bug fixes and security patches, but there will be no active development on it. 8 | 9 | We strongly recommend migrating to `2.x` using the instructions stated below. 10 | 11 | ## End Of Life Timeline 12 | 13 | Version `1.x` of the cdk8s toolchain will enter end-of-life on 01/01/25. After which, it will no longer receive any updates. 14 | 15 | We strongly recommend migrating to `2.x` using the instructions stated below. 16 | 17 | ## Core Library 18 | 19 | Version `2.x` of the core [cdk8s](https://www.npmjs.com/package/cdk8s) library is identical to version `1.x` from an API perspective. The only difference is in the dependency they declare on the `constructs` library. This also means that the documentation and code snippets presented throughout the site is compatible with `1.x` as well, in case you'd still like to use it. 20 | 21 | !!! info 22 | 23 | See [Ecosystem Interoperability](./ecosystem-interoperability.md) for reasoning behind this change. 24 | 25 | Following are instructions on what changes should be performed to use version `2.x`: 26 | 27 | === "TypeScript" 28 | 29 | In `package.json`, define: 30 | 31 | ```json 32 | "dependencies": { 33 | "cdk8s": "^2.2.87", 34 | "constructs": "^10.1.12" 35 | } 36 | ``` 37 | 38 | === "Java" 39 | 40 | In `pom.xml`, define: 41 | 42 | ```xml 43 | 44 | 45 | org.cdk8s 46 | cdk8s 47 | [2.2.86,3.0] 48 | 49 | 50 | software.constructs 51 | constructs 52 | [10.1.12,11.0.0] 53 | 54 | 55 | ``` 56 | 57 | === "Python" 58 | 59 | In `Pipfile`, define: 60 | 61 | ```console 62 | [packages] 63 | constructs = "~=10.1.12" 64 | cdk8s = "~=2.2.87" 65 | ``` 66 | 67 | === "Go" 68 | 69 | In `go.mod`, define: 70 | 71 | ```go 72 | require ( 73 | github.com/aws/constructs-go/constructs/v10 v10.1.12 74 | github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2 v2.2.87 75 | ) 76 | ``` 77 | 78 | Since major versions are encoded in go import statements, in your source code, change to: 79 | 80 | ```go 81 | import ( 82 | "github.com/aws/constructs-go/constructs/v10" 83 | "github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2" 84 | ) 85 | ``` 86 | 87 | ## CLI 88 | 89 | Version `2.x` of the [cdk8s-cli](https://www.npmjs.com/package/cdk8s-cli) is identical to version `1.x` from an API perspective. The only difference is in the project templates `cdk8s init` generates. CLI version `1.x / 2.x` will initiate projects utilizing version `1.x / 2.x` of the core library, accordingly. 90 | 91 | If you'd like to continue using version `1.x` of the CLI: 92 | 93 | === "Homebrew" 94 | 95 | [Locate the latest `1.x`](https://formulae.brew.sh/formula/cdk8s#default) version you'd like to install, and: 96 | 97 | ```console 98 | brew install cdk8s@1.. 99 | ``` 100 | 101 | === "npm" 102 | ```console 103 | npm install -g cdk8s-cli@^1 104 | ``` 105 | 106 | === "yarn" 107 | ```console 108 | yarn global add cdk8s-cli@^1 109 | ``` 110 | -------------------------------------------------------------------------------- /docs/plus/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - index.md 3 | - cdk8s-plus-30: cdk8s-plus-30 4 | - cdk8s-plus-31: cdk8s-plus-31 5 | - cdk8s-plus-32: cdk8s-plus-32 6 | -------------------------------------------------------------------------------- /docs/reference/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - index.md 3 | - cdk8s: cdk8s 4 | - cdk8s-plus-30: cdk8s-plus-30 5 | - cdk8s-plus-31: cdk8s-plus-31 6 | - cdk8s-plus-32: cdk8s-plus-32 7 | -------------------------------------------------------------------------------- /docs/reference/cdk8s-plus-27/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - TypeScript: typescript.md 3 | - Python: python.md 4 | - Java: java.md 5 | - Go: go.md -------------------------------------------------------------------------------- /docs/reference/cdk8s-plus-27/go.md: -------------------------------------------------------------------------------- 1 | # cdk8s-plus-27 (Go) 2 | 3 | For Go API reference, please visit . -------------------------------------------------------------------------------- /docs/reference/cdk8s-plus-28/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - TypeScript: typescript.md 3 | - Python: python.md 4 | - Java: java.md 5 | - Go: go.md -------------------------------------------------------------------------------- /docs/reference/cdk8s-plus-28/go.md: -------------------------------------------------------------------------------- 1 | # cdk8s-plus-28 (Go) 2 | 3 | For Go API reference, please visit . -------------------------------------------------------------------------------- /docs/reference/cdk8s-plus-29/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - TypeScript: typescript.md 3 | - Python: python.md 4 | - Java: java.md 5 | - Go: go.md -------------------------------------------------------------------------------- /docs/reference/cdk8s-plus-29/go.md: -------------------------------------------------------------------------------- 1 | # cdk8s-plus-29 (Go) 2 | 3 | For Go API reference, please visit . -------------------------------------------------------------------------------- /docs/reference/cdk8s-plus-30/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - TypeScript: typescript.md 3 | - Python: python.md 4 | - Java: java.md 5 | - Go: go.md -------------------------------------------------------------------------------- /docs/reference/cdk8s-plus-30/go.md: -------------------------------------------------------------------------------- 1 | # cdk8s-plus-30 (Go) 2 | 3 | For Go API reference, please visit . -------------------------------------------------------------------------------- /docs/reference/cdk8s-plus-31/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - TypeScript: typescript.md 3 | - Python: python.md 4 | - Java: java.md 5 | - Go: go.md -------------------------------------------------------------------------------- /docs/reference/cdk8s-plus-31/go.md: -------------------------------------------------------------------------------- 1 | # cdk8s-plus-31 (Go) 2 | 3 | For Go API reference, please visit . -------------------------------------------------------------------------------- /docs/reference/cdk8s-plus-32/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - TypeScript: typescript.md 3 | - Python: python.md 4 | - Java: java.md 5 | - Go: go.md -------------------------------------------------------------------------------- /docs/reference/cdk8s-plus-32/go.md: -------------------------------------------------------------------------------- 1 | # cdk8s-plus-32 (Go) 2 | 3 | For Go API reference, please visit . -------------------------------------------------------------------------------- /docs/reference/cdk8s/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - TypeScript: typescript.md 3 | - Python: python.md 4 | - Java: java.md 5 | - Go: go.md 6 | -------------------------------------------------------------------------------- /docs/reference/cdk8s/go.md: -------------------------------------------------------------------------------- 1 | # cdk8s (Go) 2 | 3 | For Go API reference, please visit . -------------------------------------------------------------------------------- /docs/reference/index.md: -------------------------------------------------------------------------------- 1 | # API reference 2 | 3 | This section includes API reference for the various components of cdk8s. 4 | 5 | === "TypeScript" 6 | 7 | * [**cdk8s**](./cdk8s/typescript.md) 8 | * [**cdk8s-plus-30**](./cdk8s-plus-30/typescript.md) · Kubernetes v1.30.0 9 | * [**cdk8s-plus-31**](./cdk8s-plus-31/typescript.md) · Kubernetes v1.31.0 10 | * [**cdk8s-plus-32**](./cdk8s-plus-32/typescript.md) · Kubernetes v1.32.0 11 | 12 | === "Python" 13 | 14 | * [**cdk8s**](./cdk8s/python.md) 15 | * [**cdk8s-plus-30**](./cdk8s-plus-30/python.md) · Kubernetes v1.30.0 16 | * [**cdk8s-plus-31**](./cdk8s-plus-31/python.md) · Kubernetes v1.31.0 17 | * [**cdk8s-plus-32**](./cdk8s-plus-32/python.md) · Kubernetes v1.32.0 18 | 19 | === "Java" 20 | 21 | * [**cdk8s**](./cdk8s/java.md) 22 | * [**cdk8s-plus-30**](./cdk8s-plus-30/java.md) · Kubernetes v1.30.0 23 | * [**cdk8s-plus-31**](./cdk8s-plus-31/java.md) · Kubernetes v1.31.0 24 | * [**cdk8s-plus-32**](./cdk8s-plus-32/java.md) · Kubernetes v1.32.0 25 | 26 | === "Go" 27 | 28 | * [**cdk8s**](./cdk8s/go.md) 29 | * [**cdk8s-plus-30**](./cdk8s-plus-30/go.md) · Kubernetes v1.30.0 30 | * [**cdk8s-plus-31**](./cdk8s-plus-31/go.md) · Kubernetes v1.31.0 31 | * [**cdk8s-plus-32**](./cdk8s-plus-32/go.md) · Kubernetes v1.32.0 32 | 33 | !!! info 34 | 35 | The documentation here relates to version `2.x` of the cdk8s tool-chain, which is the latest. If you are still using version `1.x`, please refer to the [Migrating from 1.x Guide](../migrating-from-1.x.md) 36 | -------------------------------------------------------------------------------- /docs/requirements.txt: -------------------------------------------------------------------------------- 1 | mkdocs 2 | mkdocs-awesome-pages-plugin 3 | mkdocs-material 4 | mkdocs-exclude 5 | mkdocs-redirects 6 | -------------------------------------------------------------------------------- /examples/go/crd/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/go/cdk8s-crd -------------------------------------------------------------------------------- /examples/go/hello/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/go/cdk8s-core -------------------------------------------------------------------------------- /examples/go/helm-bitnami/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/go/cdk8s-helm -------------------------------------------------------------------------------- /examples/go/web-service/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/go/cdk8s-composition -------------------------------------------------------------------------------- /examples/java/crd/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/java/cdk8s-crd -------------------------------------------------------------------------------- /examples/java/hello/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/java/cdk8s-core -------------------------------------------------------------------------------- /examples/java/helm-bitnami/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/java/cdk8s-helm -------------------------------------------------------------------------------- /examples/java/web-service/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/java/cdk8s-composition -------------------------------------------------------------------------------- /examples/python/crd/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/python/cdk8s-crd -------------------------------------------------------------------------------- /examples/python/hello/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/python/cdk8s-core -------------------------------------------------------------------------------- /examples/python/helm-bitnami/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/python/cdk8s-helm -------------------------------------------------------------------------------- /examples/python/web-service/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/python/cdk8s-composition -------------------------------------------------------------------------------- /examples/typescript/cdk8s-plus-elasticsearch-query/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/typescript/cdk8s-plus-elasticsearch-query -------------------------------------------------------------------------------- /examples/typescript/cdk8s-plus-ingress/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/typescript/cdk8s-plus-http-echo -------------------------------------------------------------------------------- /examples/typescript/crd/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/typescript/cdk8s-crd -------------------------------------------------------------------------------- /examples/typescript/hello/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/typescript/cdk8s-core -------------------------------------------------------------------------------- /examples/typescript/helm-bitnami/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/typescript/cdk8s-helm -------------------------------------------------------------------------------- /examples/typescript/include-dashboard/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/typescript/cdk8s-include -------------------------------------------------------------------------------- /examples/typescript/podinfo/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/typescript/cdk8s-plus-pod-info -------------------------------------------------------------------------------- /examples/typescript/web-cache-db/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/typescript/cdk8s-plus-web-cache-db -------------------------------------------------------------------------------- /examples/typescript/web-service/README.md: -------------------------------------------------------------------------------- 1 | Moved to https://github.com/cdk8s-team/cdk8s-examples/tree/main/typescript/cdk8s-composition -------------------------------------------------------------------------------- /git-hooks/README.md: -------------------------------------------------------------------------------- 1 | # Git Hooks 2 | 3 | This directory contains git hooks that the core team uses for various tasks. 4 | 5 | - Commit signoff for automatic compliance of the [DCO](../CONTRIBUTING.md#developer-certificate-of-origin-dco). 6 | 7 | ## Setup 8 | 9 | To setup these git hooks, run `./git-hooks/setup.sh` from the root directory of the project. 10 | -------------------------------------------------------------------------------- /git-hooks/prepare-commit-msg: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | NAME=$(git config user.name) 4 | EMAIL=$(git config user.email) 5 | 6 | if [ -z "$NAME" ]; then 7 | echo "empty git config user.name" 8 | exit 1 9 | fi 10 | 11 | if [ -z "$EMAIL" ]; then 12 | echo "empty git config user.email" 13 | exit 1 14 | fi 15 | 16 | git interpret-trailers --if-exists doNothing --trailer \ 17 | "Signed-off-by: $NAME <$EMAIL>" \ 18 | --in-place "$1" 19 | -------------------------------------------------------------------------------- /git-hooks/setup.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | ############################################## 4 | # Setup shared .git hooks for this project. 5 | # 6 | 7 | hooksdir="$(cd $(dirname $0) && pwd)" 8 | 9 | git config core.hooksPath ${hooksdir} 10 | echo "Configured core.hooksPath to ${hooksdir}" 11 | -------------------------------------------------------------------------------- /lerna.json: -------------------------------------------------------------------------------- 1 | { 2 | "npmClient": "yarn", 3 | "version": "0.0.0" 4 | } 5 | -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: cdk8s 2 | repo_url: https://github.com/cdk8s-team/cdk8s 3 | repo_name: cdk8s-team/cdk8s 4 | edit_uri: blob/master/docs 5 | # Used for canonical URLS and sitemap.xml 6 | site_url: https://cdk8s.io/docs/latest/ 7 | theme: 8 | name: material 9 | favicon: assets/favicon.png 10 | logo: assets/logo.png 11 | icon: 12 | repo: fontawesome/brands/github 13 | palette: 14 | scheme: default 15 | primary: '#133650' 16 | features: 17 | # Clicks on all internal links will be intercepted and dispatched via XHR without fully reloading the page 18 | # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#instant-loading 19 | - navigation.instant 20 | # Documents can be directly linked to sections, which is particularly useful for providing overview pages. 21 | # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#section-index-pages 22 | - navigation.indexes 23 | # The URL in the address bar is automatically updated with the active anchor as highlighted in the table of contents. 24 | # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#anchor-tracking 25 | - navigation.tracking 26 | # All tabs with the same label will be activated when a user clicks a content tab 27 | # https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#linked-content-tabs 28 | - content.tabs.link 29 | 30 | extra_css: 31 | - assets/extra.css 32 | 33 | markdown_extensions: 34 | - pymdownx.highlight 35 | - pymdownx.superfences 36 | - pymdownx.tabbed: 37 | alternate_style: true 38 | - pymdownx.details 39 | - admonition 40 | - pymdownx.emoji: 41 | emoji_index: !!python/name:materialx.emoji.twemoji 42 | emoji_generator: !!python/name:materialx.emoji.to_svg 43 | - smarty 44 | - toc: 45 | permalink: true 46 | toc_depth: 3 47 | title: On this page 48 | # This configuration enables Markdown table support 49 | # https://squidfunk.github.io/mkdocs-material/reference/data-tables/#data-tables 50 | - tables 51 | plugins: 52 | - search 53 | - awesome-pages 54 | # Allows us to ignore files from the final build 55 | # https://github.com/apenwarr/mkdocs-exclude 56 | - exclude: 57 | glob: 58 | - '*.sh' 59 | - 'requirements.txt' 60 | # Support redirects 61 | # https://github.com/mkmkdocs-redirects 62 | - redirects: 63 | redirect_maps: 64 | # /plus docs are now split into subdirs for each cdk8s+ version. Redirect the old traffic to the latest (cdk8s-plus-25/). 65 | plus/config-map.md: plus/cdk8s-plus-25/config-map.md 66 | plus/container.md: plus/cdk8s-plus-25/container.md 67 | plus/cronjob.md: plus/cdk8s-plus-25/cronjob.md 68 | plus/deployment.md: plus/cdk8s-plus-25/deployment.md 69 | plus/horizontal-pod-autoscaler.md: plus/cdk8s-plus-25/horizontal-pod-autoscaler.md 70 | plus/ingress.md: plus/cdk8s-plus-25/ingress.md 71 | plus/job.md: plus/cdk8s-plus-25/job.md 72 | plus/namespace.md: plus/cdk8s-plus-25/namespace.md 73 | plus/network-policy.md: plus/cdk8s-plus-25/network-policy.md 74 | plus/pod.md: plus/cdk8s-plus-25/pod.md 75 | plus/pv.md: plus/cdk8s-plus-25/pv.md 76 | plus/pvc.md: plus/cdk8s-plus-25/pvc.md 77 | plus/rbac.md: plus/cdk8s-plus-25/rbac.md 78 | plus/secret.md: plus/cdk8s-plus-25/secret.md 79 | plus/service.md: plus/cdk8s-plus-25/service.md 80 | plus/service-account.md: plus/cdk8s-plus-25/service-account.md 81 | plus/volume.md: plus/cdk8s-plus-25/volume.md 82 | 83 | 84 | # footer 85 | extra: 86 | homepage: / 87 | social: 88 | - icon: fontawesome/brands/slack 89 | link: https://cdk.dev 90 | name: Join the cdk8s Slack channel 91 | - icon: fontawesome/brands/github 92 | link: https://github.com/cdk8s-team/cdk8s 93 | name: cdk8s on GitHub 94 | - icon: fontawesome/brands/stack-overflow 95 | link: https://stackoverflow.com/questions/tagged/cdk8s 96 | name: cdk8s on Stack Overflow 97 | 98 | copyright: © 2025, Amazon Web Services, Inc. or its affiliates. © cdk8s project authors. All rights reserved. 99 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "root", 3 | "repository": { 4 | "type": "git", 5 | "url": "https://github.com/cdk8s-team/cdk8s.git" 6 | }, 7 | "scripts": { 8 | "build": "npx projen build", 9 | "clobber": "npx projen clobber", 10 | "compile": "npx projen compile", 11 | "default": "npx projen default", 12 | "eject": "npx projen eject", 13 | "eslint": "npx projen eslint", 14 | "package": "npx projen package", 15 | "post-compile": "npx projen post-compile", 16 | "post-upgrade": "npx projen post-upgrade", 17 | "pre-compile": "npx projen pre-compile", 18 | "rotate-cdk8s-plus": "npx projen rotate-cdk8s-plus", 19 | "test": "npx projen test", 20 | "upgrade-compiler-dependencies": "npx projen upgrade-compiler-dependencies", 21 | "upgrade-configuration": "npx projen upgrade-configuration", 22 | "upgrade-dev-dependencies": "npx projen upgrade-dev-dependencies", 23 | "upgrade-runtime-dependencies": "npx projen upgrade-runtime-dependencies", 24 | "watch": "npx projen watch", 25 | "projen": "npx projen" 26 | }, 27 | "author": { 28 | "name": "Amazon Web Services", 29 | "organization": false 30 | }, 31 | "devDependencies": { 32 | "@cdk8s/projen-common": "^0.0.606", 33 | "@stylistic/eslint-plugin": "^2", 34 | "@types/jest": "^26.0.24", 35 | "@types/node": "16.18.78", 36 | "@typescript-eslint/eslint-plugin": "^8", 37 | "@typescript-eslint/parser": "^8", 38 | "cdk8s": "^2.69.71", 39 | "cdk8s-cli": "^2.200.88", 40 | "cdk8s-plus-30": "^2.4.4", 41 | "cdk8s-plus-31": "^2.2.3", 42 | "cdk8s-plus-32": "^2.1.3", 43 | "constructs": "^10.0.0", 44 | "eslint": "^9", 45 | "eslint-import-resolver-typescript": "^3.10.1", 46 | "eslint-plugin-import": "^2.31.0", 47 | "jest": "^27", 48 | "jest-junit": "^16", 49 | "lerna": "^8.2.2", 50 | "projen": "^0.92.9", 51 | "semver": "^7.7.2", 52 | "ts-jest": "^27.1.5", 53 | "ts-node": "^10.9.2", 54 | "typescript": "^4.9.5" 55 | }, 56 | "resolutions": { 57 | "@types/responselike": "1.0.0", 58 | "got": "12.3.1" 59 | }, 60 | "engines": { 61 | "node": ">= 16.20.0" 62 | }, 63 | "main": "lib/index.js", 64 | "license": "Apache-2.0", 65 | "publishConfig": { 66 | "access": "public" 67 | }, 68 | "version": "0.0.0", 69 | "jest": { 70 | "coverageProvider": "v8", 71 | "testMatch": [ 72 | "/@(src|test)/**/*(*.)@(spec|test).ts?(x)", 73 | "/@(src|test)/**/__tests__/**/*.ts?(x)", 74 | "/@(projenrc)/**/*(*.)@(spec|test).ts?(x)", 75 | "/@(projenrc)/**/__tests__/**/*.ts?(x)" 76 | ], 77 | "clearMocks": true, 78 | "collectCoverage": true, 79 | "coverageReporters": [ 80 | "json", 81 | "lcov", 82 | "clover", 83 | "cobertura", 84 | "text" 85 | ], 86 | "coverageDirectory": "coverage", 87 | "coveragePathIgnorePatterns": [ 88 | "/node_modules/" 89 | ], 90 | "testPathIgnorePatterns": [ 91 | "/node_modules/" 92 | ], 93 | "watchPathIgnorePatterns": [ 94 | "/node_modules/" 95 | ], 96 | "reporters": [ 97 | "default", 98 | [ 99 | "jest-junit", 100 | { 101 | "outputDirectory": "test-reports" 102 | } 103 | ] 104 | ], 105 | "preset": "ts-jest", 106 | "globals": { 107 | "ts-jest": { 108 | "tsconfig": "tsconfig.dev.json" 109 | } 110 | } 111 | }, 112 | "types": "lib/index.d.ts", 113 | "private": true, 114 | "workspaces": { 115 | "packages": [] 116 | }, 117 | "//": "~~ Generated by projen. To modify, edit .projenrc.ts and run \"npx projen\"." 118 | } 119 | -------------------------------------------------------------------------------- /research/README.md: -------------------------------------------------------------------------------- 1 | # CDK for Kubernetes (cdk8s) - Research Facility 2 | 3 | Welcome to the *cdk8s* research facility! 4 | 5 | The goal of this facility is two fold: 6 | 7 | 1. Share the research being done by core team members with the community. 8 | 2. Collect additional ideas thought of by the community. 9 | 10 | Any form of contribution is done by simply creating a pull request with your suggested content. 11 | We also welcome you to [open](https://github.com/cdk8s-team/cdk8s/issues/new?assignees=&labels=enhancement&template=feature-request---suggestion.md&title=%5BSuggestion%5D+new+suggestion) 12 | an issue beforehand if you'd like to have a discussion prior to creating the pull request (highly encoureged). 13 | 14 | We are currently actively researching the following topics: 15 | 16 | - [High Level Abstractions](./high-level-abstractions) 17 | -------------------------------------------------------------------------------- /research/high-level-abstractions/README.md: -------------------------------------------------------------------------------- 1 | # High-Level Abstractions 2 | 3 | One of the major benefits of *cdk8s*, is the ability to create high level abstractions ontop of the basic Kubernetes building blocks. 4 | These abstractions, which we refer to as `L2` (Layer 2) constructs, are meant to simplify the interaction with kubernetes resources, and more accurately represent the mental model of the developer (author). 5 | 6 | Among others, their capabitilities should include: 7 | 8 | - Provide sane defaults. 9 | - Auto create and wire dependent resources. 10 | - Expose type-safe semantic API's the convey *intent*, rather than data. 11 | 12 | The process of hand-crafting these abstractions requires thourough research of use-cases and common patterns that emerge when authoring kubernetes applications. 13 | 14 | At a certain point, when we've collected enough such use-cases, we will start consolidating it and build 15 | the first versions of these `L2` constructs. 16 | 17 | ## Curation 18 | 19 | We structure and curate the research by focusing on **use-cases**: 20 | 21 | - Every sub-directory represents a different use-case. 22 | - Every use-case should, **at least**, include a `REAMDE` file that describes 23 | the motivation behind the suggestion. 24 | 25 | > If the use-case was inspired by external material (i.e docs, blog post, examples), the README should include a reference to that material. 26 | - Aside from the `README`, the structure of the use-case directory is free form. It can range from proposing theoretical API's without any implementation, to a full blown *cdk8s* application that can synthesized and deployed. 27 | 28 | For example: [ConfigMap as Pod volumes](./config-map-volume-in-pod) 29 | 30 | ## Contribution 31 | 32 | Kubernetes has such a rich domain, and so many different configuration options, that come along with a lot of complexity for manifest authors. We feel that the best way to create these abstractions, is to engage with the community so that we understand the needs and the pain points. 33 | 34 | *Simply put, we need you!* 35 | 36 | Here are some general guidelines: 37 | 38 | - Try focusing on specific use-cases, rather than a general design for the construct. 39 | 40 | - Put yourself in the shoes of manifest authors, how can we make their lifes easier? 41 | 42 | - While it makes since to draw inspiration from API's suggested in existing use-cases, its important you have full creative freedom, so don't feel you have to be aligned with them. 43 | 44 | Contributing to `L2` research essentially means one of: 45 | 46 | ### 1) Propose new use-cases 47 | 48 | If you have a new use-case in mind, create a new directory and give it a concise name that describes the use-case. Make sure to include a `README` file as mentioned earlier. 49 | 50 | ### 3) Suggest an alternate 51 | 52 | Sometimes you may have a different suggestion for an existing API. In such a case, **append** your suggestion to the existing one, don't replace it. Remember that this is research, so we are still not in the decision making phase, we just want all possible alternatives in front of us. 53 | 54 | > Its possible that as part of the review process, we will decide to actually replace, but lets leave that for a discussion, as we assume that more often than not, we will choose to append. 55 | 56 | ### 2) Extend existing use-cases 57 | 58 | You might also have a suggestion to extend the API of an existing use-case, feel free do so, but remember to try and focus on the use-case in question. -------------------------------------------------------------------------------- /research/high-level-abstractions/config-map-volume-in-pod/README.md: -------------------------------------------------------------------------------- 1 | # ConfigMap as Pod Volume 2 | 3 | ## Motivation 4 | 5 | A common pattern in Kubernetes is to use a ConfigMap to store the contents of some configuration and make it available to a pod via a volume (see [docs](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#populate-a-volume-with-data-stored-in-a-configmap)): 6 | 7 | In short, here is what you have to do to make this happen: 8 | 9 | 1. Use kubectl to define a ConfigMap from a directory: 10 | 11 | `kubectl create configmap my-config --from-file=./config` 12 | 13 | 2. Define the pod through this YAML: 14 | 15 | ```yaml 16 | apiVersion: v1 17 | kind: Pod 18 | metadata: 19 | name: dapi-test-pod 20 | spec: 21 | containers: 22 | - name: test-container 23 | image: registry.k8s.io/busybox 24 | command: [ "/bin/sh", "-c", "ls /etc/config/" ] 25 | volumeMounts: 26 | - name: config-volume 27 | mountPath: /etc/config 28 | volumes: 29 | - name: config-volume 30 | configMap: 31 | name: my-config 32 | restartPolicy: Never 33 | ``` 34 | 35 | ## API Suggestion 36 | 37 | In contrast, suppose we had an API of this sorts: 38 | 39 | ```typescript 40 | // define a config map with all the files in a local dir 41 | const config = ConfigMap.fromDirectory(this, './config'); 42 | 43 | // define a pod 44 | const pod = new Pod(this, 'dapi-test-pod'); 45 | 46 | // add the config map as a volume 47 | const volume = pod.addConfigMapVolume(config); 48 | 49 | // add a container to the pod and mount the files 50 | // to /etc/config, and print them on initialization 51 | const container = pod.addContainer('test-container'); 52 | container.image = 'registry.k8s.io/busybox'; 53 | container.mount(volume, '/etc/config'); // <-- NICE! 54 | container.command = "/bin/sh", "-c", "ls /etc/config/"; 55 | container.restartPolicy = PodRestartPolicy.NEVER; 56 | ``` 57 | -------------------------------------------------------------------------------- /rfc/0000-template.md: -------------------------------------------------------------------------------- 1 | # {RFC_TITLE} 2 | 3 | * **Original Author(s):**: @{AUTHOR} 4 | * **Tracking Issue**: #{TRACKING_ISSUE} 5 | * **API Bar Raiser**: @{BAR_RAISER_USER} 6 | 7 | > Write one sentence which is a brief description of the feature from a user 8 | > perspective ("impact on users"). 9 | 10 | ## Working Backwards 11 | 12 | > This section should contain one or more "artifacts from the future", as if the 13 | > feature was already released and we are publishing its CHANGELOG, README, 14 | > CONTRIBUTING.md and optionally a PRESS RELEASE. This is the most important 15 | > section of your RFC. It's a powerful thought exercise which will challenge you 16 | > to truly think about this feature from a user's point of view. 17 | > 18 | > Choose *one or more* of the options below: 19 | > 20 | > * **CHANGELOG**: Write the changelog entry for this feature in conventional 21 | > form (e.g. `feat(eks): cluster tags`). If this change includes a breaking 22 | > change, include a `BREAKING CHANGE` clause with information on how to 23 | > migrate. If migration is complicated, refer to a fictional GitHub issue and 24 | > add its contents here. 25 | > 26 | > * **README**: If this is a new feature, write the README section which 27 | > describes this new feature. It should describe the feature and walk users 28 | > through usage examples and description of the various options and behavior. 29 | > 30 | > * **PRESS RELEASE**: If this is a major feature (~6 months of work), write the 31 | > press release which announces this feature. The press release is a single 32 | > page that includes 7 paragraphs: (1) summary, (2) problem, (3) solution, (4) 33 | > leader quote, (5) user experience, (6) customer testimonial and (7) one 34 | > sentence call to action. 35 | 36 | --- 37 | 38 | Ticking the box below indicates that the public API of this RFC has been 39 | signed-off by the API bar raiser (the `api-approved` label was applied to the 40 | RFC pull request): 41 | 42 | ``` 43 | [ ] Signed-off by API Bar Raiser @xxxxx 44 | ``` 45 | 46 | ## Public FAQ 47 | 48 | > This section should include answers to questions readers will likely ask about 49 | > this release. Similar to the "working backwards", this section should be 50 | > written in a language as if the feature is now released. 51 | > 52 | > The template includes a some common questions, feel free to add any questions 53 | > that might be relevant to this feature or omit questions that you feel are not 54 | > applicable. 55 | 56 | ### What are we launching today? 57 | 58 | > What exactly are we launching? Is this a new feature in an existing module? A 59 | > new module? A whole framework? A change in the CLI? 60 | 61 | ### Why should I use this feature? 62 | 63 | > Describe use cases that are addressed by this feature. 64 | 65 | ## Internal FAQ 66 | 67 | > The goal of this section is to help decide if this RFC should be implemented. 68 | > It should include answers to questions that the team is likely ask. Contrary 69 | > to the rest of the RFC, answers should be written "from the present" and 70 | > likely discuss design approach, implementation plans, alternative considered 71 | > and other considerations that will help decide if this RFC should be 72 | > implemented. 73 | 74 | ### Why are we doing this? 75 | 76 | > What is the motivation for this change? 77 | 78 | ### Why should we _not_ do this? 79 | 80 | > Is there a way to address this use case with the current product? What are the 81 | > downsides of implementing this feature? 82 | 83 | ### What is the technical solution (design) of this feature? 84 | 85 | > Briefly describe the high-level design approach for implementing this feature. 86 | > 87 | > As appropriate, you can add an appendix with a more detailed design document. 88 | > 89 | > This is a good place to reference a prototype or proof of concept, which is 90 | > highly recommended for most RFCs. 91 | 92 | ### Is this a breaking change? 93 | 94 | > If the answer is no. Otherwise: 95 | > 96 | > Describe what ways did you consider to deliver this without breaking users? 97 | > 98 | > Make sure to include a `BREAKING CHANGE` clause under the CHANGELOG section with a description of the breaking 99 | > changes and the migration path. 100 | 101 | ### What alternative solutions did you consider? 102 | 103 | > Briefly describe alternative approaches that you considered. If there are 104 | > hairy details, include them in an appendix. 105 | 106 | ### What are the drawbacks of this solution? 107 | 108 | > Describe any problems/risks that can be introduced if we implement this RFC. 109 | 110 | ### What is the high-level project plan? 111 | 112 | > Describe your plan on how to deliver this feature from prototyping to GA. 113 | > Especially think about how to "bake" it in the open and get constant feedback 114 | > from users before you stabilize the APIs. 115 | > 116 | > If you have a project board with your implementation plan, this is a good 117 | > place to link to it. 118 | 119 | ### Are there any open issues that need to be addressed later? 120 | 121 | > Describe any major open issues that this RFC did not take into account. Once 122 | > the RFC is approved, create GitHub issues for these issues and update this RFC 123 | > of the project board with these issue IDs. 124 | 125 | ## Appendix 126 | 127 | Feel free to add any number of appendices as you see fit. Appendices are 128 | expected to allow readers to dive deeper to certain sections if they like. For 129 | example, you can include an appendix which describes the detailed design of an 130 | algorithm and reference it from the FAQ. -------------------------------------------------------------------------------- /rfc/1216-stage-pyhsical-id.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/rfc/1216-stage-pyhsical-id.png -------------------------------------------------------------------------------- /rfc/images/build-time-validation-gate.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/rfc/images/build-time-validation-gate.png -------------------------------------------------------------------------------- /rfc/images/deploy-time-validation-gate.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/rfc/images/deploy-time-validation-gate.png -------------------------------------------------------------------------------- /rfc/images/dev-time-validation-gate.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/rfc/images/dev-time-validation-gate.png -------------------------------------------------------------------------------- /rfc/images/lifecycle.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/rfc/images/lifecycle.png -------------------------------------------------------------------------------- /rfc/sandbox-submission.md: -------------------------------------------------------------------------------- 1 | This is a working document to outline responses to request for CNCF sandbox submission. 2 | 3 | ### links 4 | * [issue](https://github.com/awslabs/cdk8s/issues/280) 5 | * [process](https://github.com/cncf/toc/blob/master/process/project_proposals.adoc#sandbox-process) 6 | * [form](https://docs.google.com/forms/d/1bJhG1MuM981uQXcnBMv4Mj9yfV5_q5Kwk3qhBCLa_5A/viewform?edit_requested=true) 7 | 8 | ### responses 9 | 1. **Email address** 10 | @amazon.com 11 | 12 | 2. **Project Name** 13 | Cloud Development Kit for Kubernetes (cdk8s) 14 | 15 | 3. **Project Description** 16 | The Cloud Development Kit for Kubernetes (cdk8s) is a software development framework for defining Kubernetes applications and reusable abstractions using familiar programming languages and rich object-oriented APIs. cdk8s generates pure Kubernetes YAML - you can use cdk8s to define applications for any Kubernetes cluster running anywhere. 17 | 18 | 4. **Code repository (URL)** 19 | https://github.com/awslabs/cdk8s 20 | 21 | 5. **website (URL)** 22 | https://cdk8s.io 23 | 24 | 6. **project roadmap** 25 | https://github.com/awslabs/cdk8s/projects/1 26 | 27 | 7. **code of conduct** 28 | https://github.com/awslabs/cdk8s/blob/master/CODE_OF_CONDUCT.md 29 | 30 | ... 31 | 32 | 10. **Please explain how your project is aligned with the cloud native computing ecosystem** 33 | Traditionally, Kubernetes applications are defined with human-readable, static YAML data files which developers write and maintain. Building new applications requires writing a good amount of boilerplate config, copying code from other projects, and applying manual tweaks and customizations. As applications evolve and teams grow, these YAML files become harder to manage. Sharing best practices or making updates involves manual changes and complex migrations. 34 | 35 | YAML is an excellent format for describing the desired state of your cluster, but it does not have primitives for expressing logic and reusable abstractions. 36 | 37 | We realized this was exactly the same problem our customers had faced when defining their applications through CloudFormation templates, a problem solved by the AWS Cloud Development Kit (AWS CDK), and that we could apply the same design concepts from the AWS CDK to help all Kubernetes users. 38 | 39 | cdk8s lets you import both core Kubernetes API objects and Custom Resources (CRDs) as strongly typed classes called “constructs“. This includes using any Kubernetes API version. 40 | 41 | Using cdk8s you can publish common Kubernetes patterns as code libraries, then reference these libraries in any application. This simplifies defining and maintaining applications for all Kubernetes users and builds on top of the Kubernetes declarative API approach while fundamentally respecting its capabilities and flexibility. It also means that you can author Kubernetes applications using the languages, IDEs, tools, and techniques you are familiar with. 42 | 43 | Since cdk8s can work with any Kubernetes cluster running anywhere, including on-premises and the cloud, we believe the project and the Kubernetes community will benefit from establishing it as a CNCF sandbox project, with the goal of collaborating tightly with the community and becoming another powerful tool in the cloud native space. 44 | 45 | 11. **Please list similar projects in the CNCF or elsewhere** 46 | There are similar projects in the Kubernetes ecosystem (kustomize, jsonnet, jkcfg, kubecfg, kubegen, Pulumi, etc.) which attempt to address these gaps in various ways. Pulumi is the most similar project, but has a different focus and implementation to cdk8s. 47 | 48 | 12. **Guidelines/help for project contributors (URL)** 49 | https://github.com/awslabs/cdk8s/blob/master/CONTRIBUTING.md 50 | 51 | 13. **Explanation of alignment/overlap with existing CNCF projects (optional)** 52 | Existing CNCF projects (kustomize, jsonnet, jkcfg, etc) are focused on object generation from a set language. They enable a similar workflow to cdk8s, but are not built with the idea of leveraging familiar general purpose programming languages to accomplish this task, nor do they address the ability to support multiple standard APIs and custom APIs (through CRDs). They also do not have the standard assumption of building and vending higher order libraries. cdk8s+ (https://github.com/cdk8s-team/cdk8s-plus) is our development effort to provide an out of the box higher order library for K8s objects. 53 | 54 | 55 | 14. **Existing project overview presentation (optional)** 56 | * https://www.cncf.io/webinars/end-yaml-engineering-with-cdk8s/ 57 | * https://aws.amazon.com/blogs/containers/introducing-cdk-for-kubernetes/ 58 | -------------------------------------------------------------------------------- /src/latest-k8s-version.txt: -------------------------------------------------------------------------------- 1 | 32 -------------------------------------------------------------------------------- /src/rotate-cdk8s-plus.ts: -------------------------------------------------------------------------------- 1 | import * as fs from 'fs'; 2 | import * as path from 'path'; 3 | 4 | function replaceRefsInFile(filePath: string, toReplace: string, substitution: string) { 5 | // references in the docs files for version XX appear in the following ways: 6 | // cdk8s-plus-XX, cdk8s.plusXX, cdk8splusXX, CDK8s_PLUSXX_VERSION, cdk8s_plusXX_version 7 | // we must also replace references to outdated kubernetes versions. this shows up as: 8 | // Kubernetes v1.XX.0 9 | const referencePrefixes = ['plus-', 'plus', 'PLUS', 'Kubernetes v1.']; 10 | 11 | let curFileData = fs.readFileSync(filePath, 'utf-8'); 12 | referencePrefixes.forEach(function (referencePrefix: string) { 13 | curFileData = curFileData.replace(new RegExp(referencePrefix + toReplace, 'g'), referencePrefix + substitution); 14 | fs.writeFileSync(filePath, curFileData); 15 | }); 16 | } 17 | 18 | export function replaceOldVersionReferences(latestVersion: string) { 19 | 20 | const latestVersionNumber = Number(latestVersion); 21 | 22 | const filesToBeUpdated = ['website/layouts/index.html', 'docs/plus/.pages', 'docs/reference/.pages', 'docs/reference/index.md']; 23 | 24 | filesToBeUpdated.forEach(function (filePath: string) { 25 | for (let i = 0; i < 3; i++) { 26 | replaceRefsInFile(filePath, `${latestVersionNumber - 1 - i}`, `${latestVersionNumber - i}`); 27 | } 28 | }); 29 | 30 | // make new docs/reference/cdk8s-plus-XX/ directory and add .pages and go.md files 31 | const newDocsReferenceDir = `docs/reference/cdk8s-plus-${latestVersionNumber}/`; 32 | fs.mkdirSync(newDocsReferenceDir); 33 | const pagesFileData = fs.readFileSync(`docs/reference/cdk8s-plus-${latestVersionNumber-1}/.pages`, 'utf-8'); 34 | fs.writeFileSync(path.join(newDocsReferenceDir, '.pages'), pagesFileData); 35 | let goFileData = fs.readFileSync(`docs/reference/cdk8s-plus-${latestVersionNumber-1}/go.md`, 'utf-8'); 36 | fs.writeFileSync(path.join(newDocsReferenceDir, 'go.md'), goFileData); 37 | replaceRefsInFile(path.join(newDocsReferenceDir, 'go.md'), `${latestVersionNumber - 1}`, latestVersion); 38 | 39 | // update reference in docs/plus/index.md 40 | replaceRefsInFile('docs/plus/index.md', `${latestVersionNumber - 1}`, latestVersion); 41 | 42 | // update all references in docs/basics/** 43 | recursiveReplaceRefsInDir('docs/basics/', `${latestVersionNumber - 1}`, latestVersion); 44 | } 45 | 46 | function recursiveReplaceRefsInDir(dir: string, toReplace: string, substitution: string) { 47 | fs.readdirSync(dir, { encoding: 'utf-8' }).forEach(file => { 48 | let fullPath = path.join(dir, file); 49 | if (fs.lstatSync(fullPath).isDirectory()) { 50 | recursiveReplaceRefsInDir(fullPath, toReplace, substitution); 51 | } else { 52 | replaceRefsInFile(fullPath, toReplace, substitution); 53 | } 54 | }); 55 | } 56 | 57 | replaceOldVersionReferences(process.argv.slice(2)[0]); -------------------------------------------------------------------------------- /tools/import-spec.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | #--------------------------------------------------------------------------------------------------------------------- 3 | # Import the kubernetes OpenApi specs from https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec 4 | # and translates them to JSON Schema. These specs are later used by the 5 | # 'cdk8s import k8s' command. 6 | # 7 | # See https://github.com/instrumenta/openapi2jsonschema 8 | #--------------------------------------------------------------------------------------------------------------------- 9 | set -euo pipefail 10 | scriptdir=$(cd $(dirname $0) && pwd) 11 | rootdir=${scriptdir}/.. 12 | 13 | version=${1:-} 14 | 15 | if [ -z ${version} ]; then 16 | echo "Error: Version is required" 17 | echo "Usage: ${scriptdir}/import-spec.sh VERSION" 18 | exit 1 19 | fi 20 | 21 | schemas_dir=${rootdir}/kubernetes-schemas 22 | 23 | mkdir -p ${schemas_dir} 24 | 25 | pip install openapi2jsonschema 26 | 27 | cd ${schemas_dir} 28 | 29 | schema_dir=v${version} 30 | mkdir -p ${schema_dir} 31 | cd ${schema_dir} 32 | 33 | openapi2jsonschema --kubernetes https://raw.githubusercontent.com/kubernetes/kubernetes/v${version}/api/openapi-spec/swagger.json -o . 34 | ls | grep -v _definitions.json | xargs rm 35 | -------------------------------------------------------------------------------- /tsconfig.dev.json: -------------------------------------------------------------------------------- 1 | // ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | { 3 | "compilerOptions": { 4 | "alwaysStrict": true, 5 | "declaration": true, 6 | "esModuleInterop": true, 7 | "experimentalDecorators": true, 8 | "inlineSourceMap": true, 9 | "inlineSources": true, 10 | "lib": [ 11 | "es2020" 12 | ], 13 | "module": "CommonJS", 14 | "noEmitOnError": false, 15 | "noFallthroughCasesInSwitch": true, 16 | "noImplicitAny": true, 17 | "noImplicitReturns": true, 18 | "noImplicitThis": true, 19 | "noUnusedLocals": true, 20 | "noUnusedParameters": true, 21 | "resolveJsonModule": true, 22 | "strict": true, 23 | "strictNullChecks": true, 24 | "strictPropertyInitialization": true, 25 | "stripInternal": true, 26 | "target": "ES2020" 27 | }, 28 | "include": [ 29 | "src/**/*.ts", 30 | "test/**/*.ts", 31 | ".projenrc.ts", 32 | "projenrc/**/*.ts" 33 | ], 34 | "exclude": [ 35 | "node_modules" 36 | ] 37 | } 38 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | // ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen". 2 | { 3 | "compilerOptions": { 4 | "rootDir": "src", 5 | "outDir": "lib", 6 | "alwaysStrict": true, 7 | "declaration": true, 8 | "esModuleInterop": true, 9 | "experimentalDecorators": true, 10 | "inlineSourceMap": true, 11 | "inlineSources": true, 12 | "lib": [ 13 | "es2020" 14 | ], 15 | "module": "CommonJS", 16 | "noEmitOnError": false, 17 | "noFallthroughCasesInSwitch": true, 18 | "noImplicitAny": true, 19 | "noImplicitReturns": true, 20 | "noImplicitThis": true, 21 | "noUnusedLocals": true, 22 | "noUnusedParameters": true, 23 | "resolveJsonModule": true, 24 | "strict": true, 25 | "strictNullChecks": true, 26 | "strictPropertyInitialization": true, 27 | "stripInternal": true, 28 | "target": "ES2020" 29 | }, 30 | "include": [ 31 | "src/**/*.ts" 32 | ], 33 | "exclude": [] 34 | } 35 | -------------------------------------------------------------------------------- /website/.gitignore: -------------------------------------------------------------------------------- 1 | public/ 2 | static/docs 3 | resources/ 4 | !*.js 5 | -------------------------------------------------------------------------------- /website/.hugo_build.lock: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/.hugo_build.lock -------------------------------------------------------------------------------- /website/README.md: -------------------------------------------------------------------------------- 1 | # CDK8s.io 2 | 3 | See [cdk8s/docs/README.md](../docs/README.md) 4 | -------------------------------------------------------------------------------- /website/archetypes/default.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "{{ replace .Name "-" " " | title }}" 3 | date: {{ .Date }} 4 | draft: true 5 | --- 6 | 7 | -------------------------------------------------------------------------------- /website/build.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | set -euo pipefail 3 | scriptdir="$(cd $(dirname $0) && pwd)" 4 | 5 | get_version() { 6 | node -p "require('$1/package.json').version" 7 | } 8 | 9 | LATEST_K8S_VERSION=$(< ${scriptdir}/../src/latest-k8s-version.txt) 10 | 11 | export CDK8S_CORE_VERSION="$(get_version cdk8s)" 12 | export CDK8S_PLUSXX_MINUS_2_VERSION="$(get_version cdk8s-plus-$((${LATEST_K8S_VERSION}-2)))" 13 | export CDK8S_PLUSXX_MINUS_1_VERSION="$(get_version cdk8s-plus-$((${LATEST_K8S_VERSION}-1)))" 14 | export CDK8S_PLUSXX_VERSION="$(get_version cdk8s-plus-${LATEST_K8S_VERSION})" 15 | export CDK8S_PLUSXX_MINUS_2="$((${LATEST_K8S_VERSION}-2))" 16 | export CDK8S_PLUSXX_MINUS_1="$((${LATEST_K8S_VERSION}-1))" 17 | export CDK8S_PLUSXX="${LATEST_K8S_VERSION}" 18 | export CDK8S_CLI_VERSION="$(get_version cdk8s-cli)" 19 | 20 | hugo --minify $@ 21 | -------------------------------------------------------------------------------- /website/config.yaml: -------------------------------------------------------------------------------- 1 | baseURL: https://cdk8s.io/ 2 | languageCode: en-us 3 | title: CDK for Kubernetes 4 | googleAnalytics: UA-166333129-1 5 | 6 | disableKinds: 7 | - taxonomy 8 | - taxonomyTerm 9 | 10 | markup: 11 | goldmark: 12 | renderer: 13 | unsafe: true # Allows you to write raw html in your md files 14 | 15 | enableRobotsTXT: true 16 | 17 | params: 18 | summary: Define Kubernetes apps and components using familiar languages 19 | subtitle: Cloud Development Kit for Kubernetes 20 | description: | 21 | **cdk8s** is an open-source software development framework for defining Kubernetes 22 | applications and reusable abstractions using familiar programming languages 23 | and rich object-oriented APIs. **cdk8s** apps synthesize into standard 24 | Kubernetes manifests which can be applied to any Kubernetes cluster. 25 | 26 | features: 27 | everywhere: 28 | title: Works with Kubernetes everywhere 29 | details: | 30 | You can use cdk8s to define applications for any Kubernetes cluster 31 | running anywhere, including any cloud or on-premises. cdk8s runs locally 32 | in your development environment and produces standard Kubernetes YAML 33 | that can be applied to any cluster. 34 | languages: 35 | title: Language support 36 | details: | 37 | cdk8s lets you define applications using Typescript, JavaScript, Python, 38 | Java, and Go. Support for more languages is coming soon. 39 | imports: 40 | title: Supports core Kubernetes objects and custom resources 41 | details: | 42 | You can import objects from any Kubernetes API version and custom 43 | resource definitions to use with cdk8s. This makes it easy to use cdk8s 44 | to easily write entire Kubernetes applications and keep them up to date 45 | as applications change. 46 | gitops: 47 | title: Deploy through GitOps 48 | details: | 49 | cdk8s works great with a GitOps workflow, making it easy to see changes 50 | as you modify your configuration and between API versions. Simply use 51 | the cdk8s to synthesize new YAML configuration files and commit them to 52 | your git repo. 53 | community: 54 | title: Community-driven 55 | details: | 56 | We are building cdk8s for any developer who uses Kubernetes to define 57 | their applications. We encourage contributions of any type, from fixing 58 | typos to building new features. 59 | 60 | footer_title: Go from code to config 61 | footer_subtitle: Easily define Kubernetes applications for any cluster 62 | 63 | # Required since Hugo version 0.91.0 64 | # https://github.com/wowchemy/wowchemy-hugo-themes/discussions/2559#discussioncomment-1840591 65 | security: 66 | funcs: 67 | getenv: 68 | - ^HUGO_ 69 | - ^CDK8S_* 70 | -------------------------------------------------------------------------------- /website/layouts/sitemap.xml: -------------------------------------------------------------------------------- 1 | {{ printf "" | safeHTML }} 2 | 3 | 4 | {{ .Site.BaseURL }}sitemap-root.xml 5 | {{ now.Format "2006-01-02" }} 6 | 7 | 8 | {{ .Site.BaseURL }}docs/latest/sitemap.xml 9 | {{ now.Format "2006-01-02" }} 10 | 11 | 12 | -------------------------------------------------------------------------------- /website/static/CNAME: -------------------------------------------------------------------------------- 1 | cdk8s.io 2 | -------------------------------------------------------------------------------- /website/static/images/1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/1.png -------------------------------------------------------------------------------- /website/static/images/1_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/1_1.png -------------------------------------------------------------------------------- /website/static/images/2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/2.png -------------------------------------------------------------------------------- /website/static/images/2_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/2_1.png -------------------------------------------------------------------------------- /website/static/images/3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/3.png -------------------------------------------------------------------------------- /website/static/images/3_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/3_1.png -------------------------------------------------------------------------------- /website/static/images/4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/4.png -------------------------------------------------------------------------------- /website/static/images/5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/5.png -------------------------------------------------------------------------------- /website/static/images/animation.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/animation.gif -------------------------------------------------------------------------------- /website/static/images/asset-1902x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/asset-1902x.png -------------------------------------------------------------------------------- /website/static/images/cncf-white.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /website/static/images/csharp.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/csharp.png -------------------------------------------------------------------------------- /website/static/images/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/favicon.png -------------------------------------------------------------------------------- /website/static/images/git-small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/git-small.png -------------------------------------------------------------------------------- /website/static/images/git.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/git.png -------------------------------------------------------------------------------- /website/static/images/gke.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | gke 5 | Created with Sketch. 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | -------------------------------------------------------------------------------- /website/static/images/go.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/go.png -------------------------------------------------------------------------------- /website/static/images/ibm.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | ibm 5 | Created with Sketch. 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | -------------------------------------------------------------------------------- /website/static/images/java.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/java.png -------------------------------------------------------------------------------- /website/static/images/js.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/js.png -------------------------------------------------------------------------------- /website/static/images/logo-white-p-500.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/logo-white-p-500.png -------------------------------------------------------------------------------- /website/static/images/logo-white-p-800.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/logo-white-p-800.png -------------------------------------------------------------------------------- /website/static/images/logo-white.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/logo-white.png -------------------------------------------------------------------------------- /website/static/images/main-p-500.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/main-p-500.png -------------------------------------------------------------------------------- /website/static/images/main.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/main.png -------------------------------------------------------------------------------- /website/static/images/opengraph.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/opengraph.jpg -------------------------------------------------------------------------------- /website/static/images/py.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/py.png -------------------------------------------------------------------------------- /website/static/images/slack.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/slack.png -------------------------------------------------------------------------------- /website/static/images/ts.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/static/images/ts.png -------------------------------------------------------------------------------- /website/static/robots.txt: -------------------------------------------------------------------------------- 1 | Sitemap: https://cdk8s.io/sitemap.xml 2 | Host: cdk8s.io 3 | 4 | User-agent: * 5 | 6 | Allow: / 7 | 8 | Disallow: /docs/latest/plus/config-map 9 | Disallow: /docs/latest/plus/container 10 | Disallow: /docs/latest/plus/cronjob 11 | Disallow: /docs/latest/plus/deployment 12 | Disallow: /docs/latest/plus/horizontal-pod-autoscaler 13 | Disallow: /docs/latest/plus/ingress 14 | Disallow: /docs/latest/plus/job 15 | Disallow: /docs/latest/plus/namespace 16 | Disallow: /docs/latest/plus/network-policy 17 | Disallow: /docs/latest/plus/pod 18 | Disallow: /docs/latest/plus/pv 19 | Disallow: /docs/latest/plus/pvc 20 | Disallow: /docs/latest/plus/rbac 21 | Disallow: /docs/latest/plus/secret 22 | Disallow: /docs/latest/plus/service 23 | Disallow: /docs/latest/plus/service-account 24 | Disallow: /docs/latest/plus/volume 25 | -------------------------------------------------------------------------------- /website/static/sitemap-root.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | https://cdk8s.io/ 5 | monthly 6 | 0.8 7 | 8 | 9 | -------------------------------------------------------------------------------- /website/visuals/vectors.ai: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdk8s-team/cdk8s/04456be9a493ef20ee60f6d6cbc7400feeb225b4/website/visuals/vectors.ai --------------------------------------------------------------------------------