diff --git a/astro.config.mjs b/astro.config.mjs index da329d2..d4b921a 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -1,6 +1,7 @@ // @ts-check import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; +import starlightVersions from 'starlight-versions'; import tailwindcss from '@tailwindcss/vite'; import starlightOpenAPI, { openAPISidebarGroups } from 'starlight-openapi'; import Icons from 'unplugin-icons/vite'; @@ -140,6 +141,9 @@ export default defineConfig({ ], customCss: ['./src/styles/global.css'], plugins: [ + starlightVersions({ + versions: [{ slug: 'v0.6' }] + }), // Generate the OpenAPI documentation pages. starlightOpenAPI([ { diff --git a/package.json b/package.json index 6595a09..33565a1 100644 --- a/package.json +++ b/package.json @@ -20,6 +20,7 @@ "astro": "^5.6.1", "sharp": "^0.34.2", "starlight-openapi": "^0.21.1", + "starlight-versions": "^0.7.0", "tailwindcss": "^4.0.7", "unplugin-icons": "^22.5.0" } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 59308c3..a7f480d 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -10,10 +10,10 @@ importers: dependencies: '@astrojs/starlight': specifier: ^0.36.2 - version: 0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)) + version: 0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2)) '@astrojs/starlight-tailwind': specifier: ^4.0.2 - version: 4.0.2(@astrojs/starlight@0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)))(tailwindcss@4.1.17) + version: 4.0.2(@astrojs/starlight@0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2)))(tailwindcss@4.1.17) '@fontsource/geist': specifier: ^5.2.8 version: 5.2.8 @@ -28,16 +28,19 @@ importers: version: 2.2.413 '@tailwindcss/vite': specifier: ^4.0.7 - version: 4.1.17(vite@6.4.1(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)) + version: 4.1.17(vite@6.4.1(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2)) astro: specifier: ^5.6.1 - version: 5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3) + version: 5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2) sharp: specifier: ^0.34.2 version: 0.34.5 starlight-openapi: specifier: ^0.21.1 - version: 0.21.1(@astrojs/markdown-remark@6.3.8)(@astrojs/starlight@0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)))(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3))(openapi-types@12.1.3) + version: 0.21.1(@astrojs/markdown-remark@6.3.8)(@astrojs/starlight@0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2)))(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2))(openapi-types@12.1.3) + starlight-versions: + specifier: ^0.7.0 + version: 0.7.0(@astrojs/starlight@0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2))) tailwindcss: specifier: ^4.0.7 version: 4.1.17 @@ -1113,6 +1116,9 @@ packages: fast-uri@3.1.0: resolution: {integrity: sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==} + fault@2.0.1: + resolution: {integrity: sha512-WtySTkS4OKev5JtpHXnib4Gxiurzh5NCGvWrFaZ34m6JehfTUhKZvn9njTfw48t6JumVQOmrKqpmGcdwxnhqBQ==} + fdir@6.5.0: resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==} engines: {node: '>=12.0.0'} @@ -1132,6 +1138,10 @@ packages: fontkit@2.0.4: resolution: {integrity: sha512-syetQadaUEDNdxdugga9CpEYVaQIxOwk7GlwZWWZ19//qW4zE5bknOKeMBDYAASwnpaSHKJITRLMF9m1fp3s6g==} + format@0.2.2: + resolution: {integrity: sha512-wzsgA6WOq+09wrU1tsJ09udeR/YZRaeArL9e1wPbFg3GG2yDnC2ldKpxs4xunpFF9DgqCqOIra3bc1HWrJ37Ww==} + engines: {node: '>=0.4.x'} + fsevents@2.3.3: resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==} engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0} @@ -1403,6 +1413,9 @@ packages: mdast-util-from-markdown@2.0.2: resolution: {integrity: sha512-uZhTV/8NBuw0WHkPTrCqDOl0zVe1BIng5ZtHoDk49ME1qqcjYmmLmOf0gELgcRMxN4w2iuIeVso5/6QymSrgmA==} + mdast-util-frontmatter@2.0.1: + resolution: {integrity: sha512-LRqI9+wdgC25P0URIJY9vwocIzCcksduHQ9OF2joxQoyTNVduwLAFUzjoopuRJbJAReaKrNQKAZKL3uCMugWJA==} + mdast-util-gfm-autolink-literal@2.0.1: resolution: {integrity: sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ==} @@ -1454,6 +1467,12 @@ packages: micromark-extension-directive@3.0.2: resolution: {integrity: sha512-wjcXHgk+PPdmvR58Le9d7zQYWy+vKEU9Se44p2CrCDPiLr2FMyiT4Fyb5UFKFC66wGB3kPlgD7q3TnoqPS7SZA==} + micromark-extension-directive@4.0.0: + resolution: {integrity: sha512-/C2nqVmXXmiseSSuCdItCMho7ybwwop6RrrRPk0KbOHW21JKoCldC+8rFOaundDoRBUWBnJJcxeA/Kvi34WQXg==} + + micromark-extension-frontmatter@2.0.0: + resolution: {integrity: sha512-C4AkuM3dA58cgZha7zVnuVxBhDsbttIMiytjgsM2XbHAB2faRVaHRle40558FBN+DJcrLNCoqG5mlrpdU4cRtg==} + micromark-extension-gfm-autolink-literal@2.1.0: resolution: {integrity: sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==} @@ -1742,6 +1761,12 @@ packages: remark-directive@3.0.1: resolution: {integrity: sha512-gwglrEQEZcZYgVyG1tQuA+h58EZfq5CSULw7J90AFuCTyib1thgHPoqQ+h9iFvU6R+vnZ5oNFQR5QKgGpk741A==} + remark-directive@4.0.0: + resolution: {integrity: sha512-7sxn4RfF1o3izevPV1DheyGDD6X4c9hrGpfdUpm7uC++dqrnJxIZVkk7CoKqcLm0VUMAuOol7Mno3m6g8cfMuA==} + + remark-frontmatter@5.0.0: + resolution: {integrity: sha512-XTFYvNASMe5iPN0719nPrdItC9aU0ssC4v14mH1BCi1u0n1gAocqcujWUrByftZTbLhRtiKRyjYTSIOcr69UVQ==} + remark-gfm@4.0.1: resolution: {integrity: sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==} @@ -1761,6 +1786,9 @@ packages: remark-stringify@11.0.0: resolution: {integrity: sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==} + remark@15.0.1: + resolution: {integrity: sha512-Eht5w30ruCXgFmxVUSlNWQ9iiimq07URKeFS3hNc8cUWy1llX4KDWfyEDZRycMc+znsN9Ux5/tJ/BFdgdOwA3A==} + require-from-string@2.0.2: resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==} engines: {node: '>=0.10.0'} @@ -1831,6 +1859,12 @@ packages: '@astrojs/starlight': '>=0.34.0' astro: '>=5.5.0' + starlight-versions@0.7.0: + resolution: {integrity: sha512-obz0/sdoflXBqr1zwu12KlkioRy0bFtvbmdVyT/4Ax7LObDJXBkmSymU72Z3vj3ajKZYui0RAle2wiqghaaeOw==} + engines: {node: '>=18'} + peerDependencies: + '@astrojs/starlight': '>=0.32.0' + stream-replace-string@2.0.0: resolution: {integrity: sha512-TlnjJ1C0QrmxRNrON00JvaFFlNh5TTG00APw23j74ET7gkQpTASi6/L2fuiav8pzK715HXtUeClpBTw2NPSn6w==} @@ -2133,6 +2167,11 @@ packages: xxhash-wasm@1.1.0: resolution: {integrity: sha512-147y/6YNh+tlp6nd/2pWq38i9h6mz/EuQ6njIrmW8D1BS5nCqs0P6DG+m6zTGnNz5I+uhZ0SHxBs9BsPrwcKDA==} + yaml@2.8.2: + resolution: {integrity: sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==} + engines: {node: '>= 14.6'} + hasBin: true + yargs-parser@21.1.1: resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==} engines: {node: '>=12'} @@ -2208,12 +2247,12 @@ snapshots: transitivePeerDependencies: - supports-color - '@astrojs/mdx@4.3.10(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3))': + '@astrojs/mdx@4.3.10(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2))': dependencies: '@astrojs/markdown-remark': 6.3.8 '@mdx-js/mdx': 3.1.1 acorn: 8.15.0 - astro: 5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3) + astro: 5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2) es-module-lexer: 1.7.0 estree-util-visit: 2.0.0 hast-util-to-html: 9.0.5 @@ -2237,22 +2276,22 @@ snapshots: stream-replace-string: 2.0.0 zod: 3.25.76 - '@astrojs/starlight-tailwind@4.0.2(@astrojs/starlight@0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)))(tailwindcss@4.1.17)': + '@astrojs/starlight-tailwind@4.0.2(@astrojs/starlight@0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2)))(tailwindcss@4.1.17)': dependencies: - '@astrojs/starlight': 0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)) + '@astrojs/starlight': 0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2)) tailwindcss: 4.1.17 - '@astrojs/starlight@0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3))': + '@astrojs/starlight@0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2))': dependencies: '@astrojs/markdown-remark': 6.3.8 - '@astrojs/mdx': 4.3.10(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)) + '@astrojs/mdx': 4.3.10(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2)) '@astrojs/sitemap': 3.6.0 '@pagefind/default-ui': 1.4.0 '@types/hast': 3.0.4 '@types/js-yaml': 4.0.9 '@types/mdast': 4.0.4 - astro: 5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3) - astro-expressive-code: 0.41.3(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)) + astro: 5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2) + astro-expressive-code: 0.41.3(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2)) bcp-47: 2.1.0 hast-util-from-html: 2.0.3 hast-util-select: 6.0.4 @@ -2804,12 +2843,12 @@ snapshots: '@tailwindcss/oxide-win32-arm64-msvc': 4.1.17 '@tailwindcss/oxide-win32-x64-msvc': 4.1.17 - '@tailwindcss/vite@4.1.17(vite@6.4.1(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2))': + '@tailwindcss/vite@4.1.17(vite@6.4.1(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2))': dependencies: '@tailwindcss/node': 4.1.17 '@tailwindcss/oxide': 4.1.17 tailwindcss: 4.1.17 - vite: 6.4.1(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2) + vite: 6.4.1(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2) '@types/debug@4.1.12': dependencies: @@ -2903,12 +2942,12 @@ snapshots: astring@1.9.0: {} - astro-expressive-code@0.41.3(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)): + astro-expressive-code@0.41.3(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2)): dependencies: - astro: 5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3) + astro: 5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2) rehype-expressive-code: 0.41.3 - astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3): + astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2): dependencies: '@astrojs/compiler': 2.13.0 '@astrojs/internal-helpers': 0.7.4 @@ -2964,8 +3003,8 @@ snapshots: unist-util-visit: 5.0.0 unstorage: 1.17.2 vfile: 6.0.3 - vite: 6.4.1(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2) - vitefu: 1.1.1(vite@6.4.1(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)) + vite: 6.4.1(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2) + vitefu: 1.1.1(vite@6.4.1(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2)) xxhash-wasm: 1.1.0 yargs-parser: 21.1.1 yocto-spinner: 0.2.3 @@ -3241,6 +3280,10 @@ snapshots: fast-uri@3.1.0: {} + fault@2.0.1: + dependencies: + format: 0.2.2 + fdir@6.5.0(picomatch@4.0.3): optionalDependencies: picomatch: 4.0.3 @@ -3264,6 +3307,8 @@ snapshots: unicode-properties: 1.4.1 unicode-trie: 2.0.0 + format@0.2.2: {} + fsevents@2.3.3: optional: true @@ -3652,6 +3697,17 @@ snapshots: transitivePeerDependencies: - supports-color + mdast-util-frontmatter@2.0.1: + dependencies: + '@types/mdast': 4.0.4 + devlop: 1.1.0 + escape-string-regexp: 5.0.0 + mdast-util-from-markdown: 2.0.2 + mdast-util-to-markdown: 2.1.2 + micromark-extension-frontmatter: 2.0.0 + transitivePeerDependencies: + - supports-color + mdast-util-gfm-autolink-literal@2.0.1: dependencies: '@types/mdast': 4.0.4 @@ -3822,6 +3878,23 @@ snapshots: micromark-util-types: 2.0.2 parse-entities: 4.0.2 + micromark-extension-directive@4.0.0: + dependencies: + devlop: 1.1.0 + micromark-factory-space: 2.0.1 + micromark-factory-whitespace: 2.0.1 + micromark-util-character: 2.1.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.2 + parse-entities: 4.0.2 + + micromark-extension-frontmatter@2.0.0: + dependencies: + fault: 2.0.1 + micromark-util-character: 2.1.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.2 + micromark-extension-gfm-autolink-literal@2.1.0: dependencies: micromark-util-character: 2.1.1 @@ -4304,6 +4377,24 @@ snapshots: transitivePeerDependencies: - supports-color + remark-directive@4.0.0: + dependencies: + '@types/mdast': 4.0.4 + mdast-util-directive: 3.1.0 + micromark-extension-directive: 4.0.0 + unified: 11.0.5 + transitivePeerDependencies: + - supports-color + + remark-frontmatter@5.0.0: + dependencies: + '@types/mdast': 4.0.4 + mdast-util-frontmatter: 2.0.1 + micromark-extension-frontmatter: 2.0.0 + unified: 11.0.5 + transitivePeerDependencies: + - supports-color + remark-gfm@4.0.1: dependencies: '@types/mdast': 4.0.4 @@ -4352,6 +4443,15 @@ snapshots: mdast-util-to-markdown: 2.1.2 unified: 11.0.5 + remark@15.0.1: + dependencies: + '@types/mdast': 4.0.4 + remark-parse: 11.0.0 + remark-stringify: 11.0.0 + unified: 11.0.5 + transitivePeerDependencies: + - supports-color + require-from-string@2.0.2: {} restructure@3.0.2: {} @@ -4472,17 +4572,34 @@ snapshots: space-separated-tokens@2.0.2: {} - starlight-openapi@0.21.1(@astrojs/markdown-remark@6.3.8)(@astrojs/starlight@0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)))(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3))(openapi-types@12.1.3): + starlight-openapi@0.21.1(@astrojs/markdown-remark@6.3.8)(@astrojs/starlight@0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2)))(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2))(openapi-types@12.1.3): dependencies: '@astrojs/markdown-remark': 6.3.8 - '@astrojs/starlight': 0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)) + '@astrojs/starlight': 0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2)) '@readme/openapi-parser': 4.1.2(openapi-types@12.1.3) - astro: 5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3) + astro: 5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2) github-slugger: 2.0.0 url-template: 3.1.1 transitivePeerDependencies: - openapi-types + starlight-versions@0.7.0(@astrojs/starlight@0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2))): + dependencies: + '@astrojs/starlight': 0.36.2(astro@5.15.7(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(rollup@4.53.2)(typescript@5.9.3)(yaml@2.8.2)) + '@pagefind/default-ui': 1.4.0 + github-slugger: 2.0.0 + mdast-util-mdx-jsx: 3.2.0 + mdast-util-mdxjs-esm: 2.0.1 + remark: 15.0.1 + remark-directive: 4.0.0 + remark-frontmatter: 5.0.0 + remark-mdx: 3.1.1 + unist-util-visit: 5.0.0 + vfile: 6.0.3 + yaml: 2.8.2 + transitivePeerDependencies: + - supports-color + stream-replace-string@2.0.0: {} string-width@4.2.3: @@ -4672,7 +4789,7 @@ snapshots: '@types/unist': 3.0.3 vfile-message: 4.0.3 - vite@6.4.1(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2): + vite@6.4.1(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2): dependencies: esbuild: 0.25.12 fdir: 6.5.0(picomatch@4.0.3) @@ -4685,10 +4802,11 @@ snapshots: fsevents: 2.3.3 jiti: 2.6.1 lightningcss: 1.30.2 + yaml: 2.8.2 - vitefu@1.1.1(vite@6.4.1(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)): + vitefu@1.1.1(vite@6.4.1(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2)): optionalDependencies: - vite: 6.4.1(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2) + vite: 6.4.1(@types/node@24.10.1)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2) web-namespaces@2.0.1: {} @@ -4708,6 +4826,8 @@ snapshots: xxhash-wasm@1.1.0: {} + yaml@2.8.2: {} + yargs-parser@21.1.1: {} yocto-queue@1.2.2: {} diff --git a/src/assets/v0.6/otter-2.png b/src/assets/v0.6/otter-2.png new file mode 100644 index 0000000..0facec1 Binary files /dev/null and b/src/assets/v0.6/otter-2.png differ diff --git a/src/content.config.ts b/src/content.config.ts index 50cb18c..5a2f650 100644 --- a/src/content.config.ts +++ b/src/content.config.ts @@ -1,7 +1,9 @@ import { defineCollection } from 'astro:content'; import { docsLoader } from '@astrojs/starlight/loaders'; import { docsSchema } from '@astrojs/starlight/schema'; +import { docsVersionsLoader } from 'starlight-versions/loader'; export const collections = { - docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }) + docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }), + versions: defineCollection({ loader: docsVersionsLoader() }) }; diff --git a/src/content/docs/v0.6/basic/configuration/01-ntp-server.mdx b/src/content/docs/v0.6/basic/configuration/01-ntp-server.mdx new file mode 100644 index 0000000..bd5806a --- /dev/null +++ b/src/content/docs/v0.6/basic/configuration/01-ntp-server.mdx @@ -0,0 +1,47 @@ +--- +title: NTP Server +description: Configure NTP server for OtterScale. +slug: v0.6/basicconfiguration/01-ntp-server +--- + +import { Steps } from '@astrojs/starlight/components'; + +This page allows you to configure the Network Time Protocol (NTP) servers used by the OtterScale system for time synchronization. Accurate timekeeping is crucial for distributed systems and log consistency. + +## Introduction + +The NTP Server configuration page allows you to manage the time synchronization sources for your OtterScale infrastructure. Here you can view and modify the list of NTP servers that will be used across all scopes. + +**Key Points:** + +* **Scope:** These settings apply to all scopes. Any changes made here will affect time synchronization for MAAS itself, all deployed machines, and devices using MAAS's DHCP services. +* **Default Configuration:** By default, OtterScale uses `ntp.ubuntu.com` as the NTP server. +* **Address Format:** You can specify NTP servers using either IP addresses (e.g., `192.168.1.1`) or hostnames (e.g., `pool.ntp.org`, `time.google.com`). +* **Multiple Servers:** It's recommended to configure multiple NTP servers for redundancy. If one server becomes unavailable, the system will automatically fall back to alternative servers. +* **Display:** Each configured server is displayed with a clock icon in the configuration list. + +## Why is NTP Important? + +NTP (Network Time Protocol) is used to synchronize the clocks of computers over a network. In a cluster environment like OtterScale, it serves several critical functions: + +* **Log Analysis**: Synchronized time is essential for correlating logs across different servers to debug issues effectively. +* **Distributed Consistency**: Distributed systems (e.g., databases, consensus algorithms) rely on accurate time to maintain data integrity and order of operations. +* **Security**: Many security protocols (like TLS/SSL certificates and Kerberos) rely on time validation. Significant time drift can cause authentication failures. +* **Scheduled Tasks**: Ensures that automated tasks and backups run at the correct coordinated times. + +## Edit NTP Servers + +To modify the NTP server list, follow these steps: + + + 1. Click the **Edit** button (pencil icon) located at the top right of the configuration section. + + 2. A modal window titled "Edit NTP Server" will appear. + + 3. In the **Address** field, you can manage the list of NTP servers: + + * **Add a server:** Type the NTP server address (e.g., `pool.ntp.org`) in the input field and click the **+** button to add it to the list (or press Enter). + * **Remove a server:** Click the **×** icon next to an existing address to delete it from the list. + + 4. Click **Confirm** to save your changes. The system will update the configuration and the new list will be displayed. + diff --git a/src/content/docs/v0.6/basic/configuration/02-boot-image.mdx b/src/content/docs/v0.6/basic/configuration/02-boot-image.mdx new file mode 100644 index 0000000..5cccdef --- /dev/null +++ b/src/content/docs/v0.6/basic/configuration/02-boot-image.mdx @@ -0,0 +1,51 @@ +--- +title: Boot Image +description: Configure boot image for OtterScale. +slug: v0.6/basicconfiguration/02-boot-image +--- + +import { Steps } from '@astrojs/starlight/components'; + +This page allows you to manage the operating system images (Boot Images) available for provisioning machines in the OtterScale cluster. These images are typically Ubuntu LTS releases. + +## Introduction + +The Boot Image settings page displays a list of configured boot images. The table includes the following information: + +* **Name**: The display name of the operating system (e.g., Ubuntu 22.04 LTS). +* **Source**: The URL of the image repository. +* **Distro Series**: The codename of the distribution release (e.g., `jammy`, `noble`). +* **Default**: Indicates if this is the default image used when no specific image is requested. +* **Architecture**: The CPU architectures supported by this image (e.g., `amd64`, `arm64`). +* **Status**: Shows the sync status of the image architectures. + +## Manage Boot Images + +You can perform the following actions to manage boot images: + +### Create a New Boot Image + +To add a new boot image configuration: + + + 1. Click the **Create** button (plus icon) at the top of the page. + + 2. A modal window titled "Create Boot Image" will appear. + + 3. **Select Distro Series**: Choose the desired Ubuntu release from the dropdown menu. + + 4. **Select Architecture**: Choose one or more CPU architectures to support for this release. + + 5. Click **Confirm** to save. The system will begin tracking this image configuration. + + +### Import Images + +To synchronize the local image cache with the upstream source: + +1. Click the **Import** button (refresh icon). +2. The system will trigger a background process to download and update the images. The button will show an "Importing..." state with a spinner while the process is running. + +### Set Default Image + +The image marked with a circle icon in the **Default** column is the current default. To change the default image, use the actions menu (three dots) on the desired image row and select **Set Default**. diff --git a/src/content/docs/v0.6/basic/configuration/03-machine-tag.mdx b/src/content/docs/v0.6/basic/configuration/03-machine-tag.mdx new file mode 100644 index 0000000..f050b17 --- /dev/null +++ b/src/content/docs/v0.6/basic/configuration/03-machine-tag.mdx @@ -0,0 +1,62 @@ +--- +title: Machine Tag +description: Configure machine tags for OtterScale. +slug: v0.6/basicconfiguration/03-machine-tag +--- + +import { Steps } from '@astrojs/starlight/components'; + +This page allows you to manage tags that can be assigned to machines in the OtterScale cluster for filtering and group management. These tags help in organizing and managing machines based on their characteristics or purposes. + +## Introduction + +The Machine Tag settings page displays a list of all existing tags in a table format. Tags are identifiable labels that can be assigned to machines for various purposes such as: + +* **Role Identification**: Marking machines by their function (e.g., `kubernetes-worker`, `kubernetes-control-plane`, `ceph-osd`) +* **Hardware Features**: Identifying specific capabilities (e.g., `virtual` for VMs) +* **Grouping**: Organizing machines for bulk operations or filtering + +### Table Columns + +* **TAG**: The unique name of the tag (e.g., `virtual`, `kubernetes`, `ceph`). +* **COMMENT**: A description or note associated with the tag. Tags with "built-in" comment are system-managed tags that cannot be deleted. + +## Manage Machine Tags + +You can create new tags or delete existing ones. + +### Create a New Tag + +To create a custom tag: + + + 1. Click the **Create** button (plus icon) at the top of the page. + + 2. A modal window titled "Create Machine Tag" will appear. + + 3. **Name**: Enter a unique name for the tag. + + 4. **Comment**: (Optional) Enter a description for the tag. + + 5. Click **Confirm** to save. The new tag will appear in the list. + + +### Delete a Tag + +To remove a tag: + + + 1. Locate the tag you want to remove in the list. + + 2. Click the **Delete** button (trash icon) in the actions column. + + * **Note**: Built-in system tags (those with "built-in" in the comment field) cannot be deleted. The Delete link will be grayed out and disabled for these tags. + + 3. A confirmation modal will appear. You must type the name of the tag to confirm deletion. + + 4. Click **Confirm** to permanently delete the tag. + + +:::caution +Deleting a tag will remove it from all machines that currently have this tag assigned. This action cannot be undone. +::: diff --git a/src/content/docs/v0.6/basic/configuration/04-package-repository.mdx b/src/content/docs/v0.6/basic/configuration/04-package-repository.mdx new file mode 100644 index 0000000..1a4cd70 --- /dev/null +++ b/src/content/docs/v0.6/basic/configuration/04-package-repository.mdx @@ -0,0 +1,42 @@ +--- +title: Package Repository +description: Configure package repositories for OtterScale. +slug: v0.6/basicconfiguration/04-package-repository +--- + +import { Steps } from '@astrojs/starlight/components'; + +Package repositories contain software packages that can be installed on machines. These repositories can be configured with custom URLs and enabled/disabled as needed to control software sources and updates for your infrastructure. + +## Introduction + +The Package Repository settings page displays a list of configured repositories in a table format. By default, OtterScale includes standard Ubuntu repositories such as: + +* **Ubuntu extra architectures**: Provides packages for additional CPU architectures +* **Ubuntu archive**: The main Ubuntu package repository + +### Table Columns + +* **NAME**: The display name of the repository (e.g., `Ubuntu extra architectures`, `Ubuntu archive`). +* **URL**: The base URL of the repository (e.g., `http://ports.ubuntu.com/ubuntu-ports`, `http://tw.archive.ubuntu.com/ubuntu`). +* **ENABLED**: A toggle indicator showing whether the repository is currently active. + +## Manage Package Repositories + +You can modify the URL of existing package repositories. This is useful if you want to point to a local mirror or a different upstream source to improve download speeds or manage bandwidth. + +### Edit Repository URL + +To change the URL of a package repository: + + + 1. Locate the repository you want to modify in the list. + + 2. Click the **Edit** button (displayed with a pencil icon) on the right side of the row. + + 3. A modal window titled "Edit Package Repository" will appear. + + 4. **URL**: Enter the new URL for the repository. + + 5. Click **Confirm** to save your changes. + diff --git a/src/content/docs/v0.6/basic/machines.mdx b/src/content/docs/v0.6/basic/machines.mdx new file mode 100644 index 0000000..17bad17 --- /dev/null +++ b/src/content/docs/v0.6/basic/machines.mdx @@ -0,0 +1,166 @@ +--- +title: Machines +description: Manage machines in OtterScale. +slug: v0.6/basic/machines +--- + +import { Card, CardGrid, Steps, Aside, Icon } from '@astrojs/starlight/components'; + +The Machines section allows you to manage the **physical machines** (bare metal) in your infrastructure. The list of machines is retrieved directly from MAAS. + + + +## Introduction + +The Machines page displays a comprehensive list of all machines in your scope, along with real-time statistics and management tools. + +### Statistics Overview + +At the top of the page, you will find a dashboard summarizing the state of your infrastructure based on the current filters: + + + + Total number of machines currently listed. + + + + The percentage and count of machines that are currently powered on. + + + + The percentage and count of machines that are successfully deployed. + + + + The total number of physical disks and the aggregate storage capacity across all listed + machines. + + + +### Data Table + +The table provides detailed information for each machine. You can toggle column visibility using the **Columns** button. + +| Column | Description | +| :---------------------- | :------------------------------------------------------------------------------------------------------------ | +| **FQDN / IP** | The Fully Qualified Domain Name and IP addresses. Click the FQDN to view [machine details](#machine-details). | +| **Power** | Current power state (On/Off) and the power control type (e.g., IPMI, Manual). | +| **Status** | The current deployment status (e.g., Deployed, Ready, Commissioning). | +| **Core / Architecture** | Number of CPU cores and the system architecture (e.g., amd64). | +| **RAM** | Total available RAM. | +| **Disk** | Number of physical disk drives detected. | +| **Storage** | Total storage capacity. | +| **GPU** | Details of installed GPUs, if any. | +| **Scope** | The scope to which the machine is assigned. | +| **Tags** | Tags assigned to the machine for organization. | +| **Memory** | A real-time bar chart indicating memory usage. | +| **Storage** | A real-time bar chart indicating storage usage. | +| **Actions** | Quick actions available for the machine, such as **Power Off** or **Remove**. | + +## Manage Machine + +You can perform management actions on individual machines using the action menu or specific buttons. + +### Power Off + +Turns off the machine. +This action is only available when the machine is currently powered on. + + + +### Remove + +Permanently removes the machine from the system. + + + +* **Options**: + * **Force**: Force removal even if the machine is not in a valid state. + * **Purge Disk**: Securely erase the disk contents during removal. + +### Adding to Scope + +To add a machine to a specific scope: + + + 1. Navigate to `https:///scope//setup`. + 2. Click the **Add Node** button. + 3. Select the machine that has not yet been registered to a scope to add it. + + +## Machine Details + +Clicking the FQDN of a machine takes you to the machine details page (`https:///machines/metal/`), which provides a comprehensive view of the machine's hardware and status. + +### Header Information + +The top of the page displays the machine's **ID**, **FQDN**, and assigned **Tags**. If the machine is not in a 'Deployed' state, an alert will be displayed. + +### Statistics Cards + +The page features several cards providing a quick overview of the machine's resources: + + + + Displays the power type (e.g., IPMI), current power state (On/Off), deployment status, and OS + details (System, Kernel, Distro). + + + + Shows the CPU architecture, total core count, and the specific CPU model. + + + + Indicates the total available RAM. + + + + Displays the total storage capacity and the number of physical disks. + + + + Provides details on the system product, vendor, and mainboard firmware (vendor and version). + Hovering over the info icon reveals more detailed hardware specifications. + + + +### Hardware Details + +Detailed hardware configurations are listed in expandable tables: + +#### Block Devices + +Lists all storage devices attached to the machine with the following details: + +| Field | Description | +| :------------------- | :---------------------------------------- | +| **Name** | Device identifier (e.g., sda). | +| **Model & Serial** | Manufacturer model and serial number. | +| **Boot Disk** | Indicates if it is the boot device. | +| **Firmware Version** | Current firmware version of the drive. | +| **Type** | Drive type (e.g., SSD, HDD). | +| **Used For** | Current usage status. | +| **Tags** | Any tags assigned to the specific device. | + +#### Network + +Lists all network interfaces with the following details: + +| Field | Description | +| :------------------------- | :--------------------------------------------------- | +| **Name / MAC** | Interface name and MAC address. | +| **IP / Subnet** | Assigned IP address and subnet. | +| **Link Speed / Connected** | Current link speed and connection status. | +| **Fabric / VLAN** | Network fabric and VLAN configuration. | +| **Type** | Interface type (e.g., physical, bond). | +| **DHCP** | Whether DHCP is enabled. | +| **Boot Interface** | Indicates if this is the interface used for booting. | +| **Interface Speed** | The capability speed of the interface. | diff --git a/src/content/docs/v0.6/basic/networking.mdx b/src/content/docs/v0.6/basic/networking.mdx new file mode 100644 index 0000000..cedc89f --- /dev/null +++ b/src/content/docs/v0.6/basic/networking.mdx @@ -0,0 +1,102 @@ +--- +title: Networking +description: Manage networking in OtterScale. +slug: v0.6/basic/networking +--- + +import { Steps, Aside, Card, CardGrid } from '@astrojs/starlight/components'; + +This page allows you to manage the network infrastructure for the OtterScale cluster. You can manage network fabrics, VLANs, and subnets for machine provisioning and service connectivity. + +### Statistics Overview + +At the top of the page, a set of summary cards provides a quick overview of the configured networking resources.: + + + + Total number of Fabrics available for network segmentation. + + + + Overall utilization of IP address space across all subnets. + + + +## Introduction + +The Networking page displays a list of configured networks. The table includes the following information: + +| Column | Description | +| :------------- | :----------------------------------------------------------------------------------- | +| **Fabric** | The physical network fabric associated with the network. | +| **VLAN** | The Virtual LAN (VLAN) ID and name. | +| **DHCP On** | Indicates whether DHCP is enabled for this network. | +| **Subnet** | The CIDR notation of the subnet (e.g., `192.168.1.0/24`) and the Gateway IP address. | +| **IP Address** | The number of IP addresses currently in use or reserved. | +| **IP Range** | The configured IP ranges for dynamic allocation. | +| **Statistics** | Visual representation of IP address usage (Available vs. Total). | + +## Manage Networks + +A Fabric represents a physical or logical L2 broadcast domain. Within each Fabric, you can define VLANs. Each VLAN containes one Subnet, which represent routable IP networks used for DHCP, PXE booting, and machine allocation. +You can create new networks or manage existing ones using the **Actions** menu (three dots icon) in each row. + +### Create a New Network + +To add a new network configuration: + + + 1. Click the **Create** button (plus icon) at the top of the page. + + 2. A modal window titled "Create Network" will appear. + + 3. Configure **VLAN Settings**: + * **Name**: Enter a name for the VLAN. + :::note + The prefix `fabric-*` is reserved for system use and cannot be used for custom network names. + ::: + * **DHCP On**: Toggle this switch to enable or disable DHCP service for this network. + + 4. Configure **Subnet Settings**: + + * **CIDR**: Enter the Classless Inter-Domain Routing (CIDR) notation for the subnet (e.g., `10.0.0.0/24`). + * **Gateway**: Enter the IP address of the network gateway. + * **DNS**: Add one or more DNS server IP addresses. + + 5. Click **Confirm** to create the network. + + +### Network Actions + +The **Actions** menu provides granular control over the different components of a network row: + +#### Edit Fabric + +Allows you to rename the physical fabric associated with the network. + +#### Edit VLAN + +Allows you to modify VLAN properties: + +* **Name**: Rename the VLAN. +* **MTU**: Set the Maximum Transmission Unit size. +* **Description**: Add or update the description. +* **DHCP On**: Enable or disable DHCP for this VLAN. + +#### Edit Subnet + +Allows you to modify subnet properties: + +* **Name**: Rename the subnet. +* **Description**: Add or update the description. +* **CIDR**: Update the subnet mask/range. +* **Gateway**: Change the gateway IP address. +* **DNS**: Manage DNS servers and toggle DNS resolution. + +#### Delete Fabric + +Permanently removes the fabric and its associated network configuration. + + diff --git a/src/content/docs/v0.6/create-scope.md b/src/content/docs/v0.6/create-scope.md new file mode 100644 index 0000000..61aa434 --- /dev/null +++ b/src/content/docs/v0.6/create-scope.md @@ -0,0 +1,24 @@ +--- +title: Scope +description: Manage scopes in OtterScale. +slug: v0.6/create-scope +--- + +Scopes allow you to organize your resources and control access. + +## Selecting a Scope + +You can select a scope from the dropdown menu in the navigation bar. This will filter the resources you see to only those within the selected scope. + +## Creating a Scope + +To create a new scope: + +1. Navigate to the Scope management area. +2. Click on "Create Scope". +3. Enter the necessary details. +4. Confirm the creation. + +## Managing Scopes + +You can manage existing scopes, including updating settings and managing access. diff --git a/src/content/docs/v0.6/demos/01-virtual-machine.mdx b/src/content/docs/v0.6/demos/01-virtual-machine.mdx new file mode 100644 index 0000000..55cc5be --- /dev/null +++ b/src/content/docs/v0.6/demos/01-virtual-machine.mdx @@ -0,0 +1,185 @@ +--- +title: Virtual Machine +description: Create and provision a Virtual Machine within the OtterScale cluster. +slug: v0.6/demos/01-virtual-machine +--- + +import { Steps, Aside, LinkCard } from '@astrojs/starlight/components'; + +This guide demonstrates how to create and provision a Virtual Machine (VM) within the OtterScale cluster for running workloads. + +## Prepare Data Volume (Boot Image) + +Before creating a Virtual Machine, you need to create a Data Volume (Persistent Volume Claim) that will serve as the bootable OS disk for the VM. + + + 1. Navigate to the Data Volume section: + + * Open your browser and go to: + + ``` + /scope//service/data-volume + ``` + + 2. Create a new Data Volume for the VM boot disk: + + * Click the **Create** button (plus icon) at the top of the Data Volume page + * A modal window titled "Create Data Volume" will appear + + 3. Configure the boot image Data Volume (PVC): + + * **Name**: Enter a unique name for the boot disk (e.g., `ubuntu-20.04-vm-boot`) + * **Namespace**: Specify the Kubernetes namespace (defaults to `kubevirt`) + * **Size**: Set the capacity of the volume (e.g., 20 GB for a typical VM) + * **Boot Image**: Toggle this option to enable the boot image mode (this will display the source input field) + * **Source**: Enter the URL of the bootable OS image: + * Example: `https://cloud-images.ubuntu.com/focal/current/focal-server-cloudimg-amd64.img` + * You can use the "Cloud Image" button to browse common Ubuntu cloud images + + 4. Click **Confirm** to create the boot image Data Volume: + + * The PVC will begin importing the OS image from the specified source + * Monitor the progress in the Data Volume list + * Wait until the **Phase** changes to **Succeeded** before proceeding to create the VM + + + + +## Create a Virtual Machine + + + + + 1. Navigate to the Compute section: + + Open your browser and go to: + + ``` + /scope//compute + ``` + + 2. Create a new Virtual Machine: + + * Click the **Create** button (plus icon) at the top of the Compute page + * A modal window titled "Create Virtual Machine" will appear + + 3. Configure Basic Settings: + + * **Name**: Enter a unique name for the VM (e.g., `my-demo-vm`) + * **Namespace**: Specify the Kubernetes namespace (defaults to `kubevirt`) + * **Instance Type**: Select a hardware profile from the dropdown list (displays CPU cores and Memory size) + * **Data Volume**: Select the bootable Data Volume (PVC) to use as the OS disk + + 4. Configure Advanced Settings (Optional): + + * Expand the "Advanced" section to configure a **Startup Script** (Cloud-Init user data) + * This allows you to bootstrap the instance with custom initialization commands + * Example configuration for user setup and SSH access: + + ``` + #cloud-config + users: + - name: phison + sudo: ['ALL=(ALL) NOPASSWD:ALL'] + groups: sudo + shell: /bin/bash + chpasswd: + list: | + phison:phison_8299 + expire: false + ssh_pwauth: true + ``` + + 5. Review and Confirm: + + * Review all the configuration settings + * Click **Confirm** to launch the Virtual Machine + + 6. Wait for VM Initialization: + + * The VM will begin provisioning and cloning a Data Volume for its use + * Monitor the **Status** column to track the initialization progress + * Wait until the status changes to **Running** + + +## Monitor the Virtual Machine + +Once the VM is created, you can monitor its status in the Compute page: + + + 1. View the VM in the Compute list: + + * Locate your newly created VM by name in the table + * Check the **Status** column to see the current state (e.g., Running, Stopped) + + 2. Access VM resources: + + * **Machine**: Click to view which physical node is hosting your VM + * **Disk**: Expand to view and manage attached storage volumes + * **Ports**: Expand to view and manage network port configurations + * **Metrics**: Monitor real-time CPU, Memory, and Storage usage + * **VNC**: Access the VM console directly through VNC + + +## Configure Service for VM Access + +To enable external access to your Virtual Machine, configure a service to expose its ports: + + + 1. Add a service port for SSH access: + + * In the Compute page, locate your VM in the table + * Click on the **Ports** column to expand the port management section + * Click **Add Port** to create a new service port + * Configure the port settings: + * **Protocol**: `tcp` + * **Port**: `22` (SSH service port on the VM) + * **NodePort**: (leave empty for automatic assignment or specify a fixed port) + * The system will automatically assign a NodePort (e.g., `30022`) for external access + + 2. Note the NodePort: + + * Record the assigned NodePort from the Ports section + * This is the port you'll use to connect to the VM from outside the cluster + + +## Access Your Virtual Machine + +Once the VM is running, fully initialized, and the service port is configured: + + + 1. Wait for cloud-init initialization: + + * The VM will automatically execute the cloud-init configuration + * The system user `phison` will be created with sudo privileges + * The password will be set as configured in the cloud-config + + 2. Connect to the VM: + + * Use SSH to connect to your VM from external hosts + * Connection example: + ``` + ssh -p phison@ + ``` + * Or use VNC to connect directly through the web interface + * Login credentials: + * **Username**: `phison` + * **Password**: `phison_8299` + + 3. Start using your VM: + + * You now have full access to configure and use the Virtual Machine + * The user has sudo privileges for system administration tasks + + +## Next Steps + +Explore other demo applications and services to enhance your infrastructure: + + + + diff --git a/src/content/docs/v0.6/demos/02-coder.mdx b/src/content/docs/v0.6/demos/02-coder.mdx new file mode 100644 index 0000000..93be354 --- /dev/null +++ b/src/content/docs/v0.6/demos/02-coder.mdx @@ -0,0 +1,72 @@ +--- +title: Coder +description: Deploy Coder for cloud-based VS Code IDE environments with support + for both Go and Python backends. +slug: v0.6/demos/02-coder +--- + +import { Steps, Aside, LinkCard } from '@astrojs/starlight/components'; + +This guide demonstrates how to deploy Coder to provide cloud-based VS Code IDE environments for development and coding. + +## Deploy Coder + + + + + 1. Navigate to the Applications Store: + + Open your browser and go to: + + ``` + /scope//applications/store + ``` + + 2. Search and install Coder: + + * Search for `code-server` (available versions: `code-server-go` or `code-server-python`) + * Choose your preferred version (Go for better performance, Python for flexibility) + * Click on the Coder card + * Click the **Install** button and follow the installation wizard + * Review and confirm the Helm Chart configuration + + 3. Verify the deployment: + + Go to the Workloads page: + + ``` + /scope//applications/workloads + ``` + + * Use the **Namespace** filter to find the deployment + * Search for `coder` or `code-server` to locate the deployed Coder workload + * Verify that the workload status shows as running + + 4. Access Coder VS Code IDE: + + * In the Workloads list, locate the Coder workload + * Click on the **NodePort** link to open VS Code in your browser + + + + +## Initial Setup + +Once Coder is deployed and running: + +1. Access the VS Code IDE through the NodePort link in your browser +2. You'll see the VS Code interface with a file explorer and terminal +3. Start creating or editing files directly in the browser-based editor +4. Use the integrated terminal for running commands and development tasks + +## Next Steps + +Explore other demo applications to enhance your infrastructure: + + + + diff --git a/src/content/docs/v0.6/demos/03-jupyterhub.mdx b/src/content/docs/v0.6/demos/03-jupyterhub.mdx new file mode 100644 index 0000000..d4189be --- /dev/null +++ b/src/content/docs/v0.6/demos/03-jupyterhub.mdx @@ -0,0 +1,75 @@ +--- +title: JupyterHub +description: Deploy JupyterHub for multi-user Jupyter notebook environments. +slug: v0.6/demos/03-jupyterhub +--- + +import { Steps, Aside, LinkCard } from '@astrojs/starlight/components'; + +This guide demonstrates how to deploy JupyterHub to provide collaborative Jupyter notebook environments for multiple users. + +## Deploy JupyterHub + + + + + 1. Navigate to the Applications Store: + + Open your browser and go to: + + ``` + /scope//applications/store + ``` + + 2. Search and install JupyterHub: + + * Search for `jupyterhub` + * Click on the JupyterHub card + * Click the **Install** button and follow the installation wizard + * Review and confirm the Helm Chart configuration + + 3. Verify the deployment: + + Go to the Workloads page: + + ``` + /scope//applications/workloads + ``` + + * Use the **Namespace** filter to find the deployment + * Search for `jupyterhub` to locate the deployed JupyterHub workload + * Verify that the workload status shows as running + + 4. Access JupyterHub: + + * In the same Workloads list, locate the workload named **proxy** + * Click on the **NodePort** link to open JupyterHub in your browser + + + + +## Initial Setup + +Once JupyterHub is deployed and running: + +1. Access the JupyterHub login page +2. Create or log in with your credentials +3. Start a new notebook server +4. Begin using Jupyter notebooks for data analysis and development + +## Next Steps + +Explore other demo applications to enhance your infrastructure: + + + + diff --git a/src/content/docs/v0.6/demos/04-llm-model.mdx b/src/content/docs/v0.6/demos/04-llm-model.mdx new file mode 100644 index 0000000..8d79a5b --- /dev/null +++ b/src/content/docs/v0.6/demos/04-llm-model.mdx @@ -0,0 +1,103 @@ +--- +title: LLM Model +description: Deploy and test LLM models integrated with OpenAI API. +slug: v0.6/demos/04-llm-model +--- + +import { Steps, Aside, Tabs, TabItem } from '@astrojs/starlight/components'; + +This guide demonstrates how to deploy a Large Language Model (LLM) in your OtterScale cluster and test it using Python with OpenAI API integration. + +## Deploy LLM Model + + + + + 1. Navigate to the **Models** page in your OtterScale cluster. + + 2. Click the **Create** button to create a new model. + + 3. Select a model from your model artifacts: + * Search for available models using the cloud icon in the search box + * Or click the archive icon to browse model artifacts + * Select your desired LLM (e.g., `meta-llama/Llama-2-7b-chat`) + + 4. Configure the model deployment: + * **Name**: Choose a descriptive name (e.g., `llm-demo`) + * **Namespace**: Select your target namespace + * **Prefill Configuration**: Set vGPU memory %, replica count, and tensor configuration (if needed) + * **Decode Configuration**: Set decoding parameters similarly + * **Description**: Add any relevant notes about the deployment + + 5. Review the configuration and click **Create** to deploy the model. + + 6. Monitor the deployment status on the Models page. The status will change from `Pending` → `Running` → `Ready`. + + 7. Once the status shows **Ready**, click the **Test** button to verify the model API is working. + + + + +## Test with Python + +Once your LLM model is deployed and ready, you can test it using Python with OpenAI API integration. + + + +### Connection Information + +Before running the test scripts, you'll need to find the following information from the `/scope//models/llm` page: + +* **Service URL**: The URL information from the Service card +* **Name**: The `name` field in the model table +* **Model Name**: The `Model Name` field in the model table + +```python +import requests +import json + +# Configuration +SERVICE_URL = "" # e.g., http://localhost:8000 +NAME = "" # e.g., llm-demo +MODEL_NAME = "" + +def ask_question(question): + """Send a simple question to the LLM and get a response.""" + headers = { + "OtterScale-Model-Name": NAME, + "Content-Type": "application/json" + } + + payload = { + "model": MODEL_NAME, + "prompt": question + } + + try: + response = requests.post( + f"{SERVICE_URL}/v1/completions", + headers=headers, + json=payload + ) + response.raise_for_status() + result = response.json() + return result.get("response", result) + except Exception as e: + return f"✗ Error: {str(e)}" + +# Test +question = "Are you alive? Please respond if you can process this message." +answer = ask_question(question) +print(f"Q: {question}") +print(f"A: {answer}") +``` diff --git a/src/content/docs/v0.6/demos/05-postgres.mdx b/src/content/docs/v0.6/demos/05-postgres.mdx new file mode 100644 index 0000000..d76dfc1 --- /dev/null +++ b/src/content/docs/v0.6/demos/05-postgres.mdx @@ -0,0 +1,279 @@ +--- +title: PostgreSQL +description: Deploy PostgreSQL database using Helm charts from the registry. +slug: v0.6/demos/05-postgres +--- + +import { Steps, Aside, Tabs, TabItem } from '@astrojs/starlight/components'; + +This guide demonstrates how to deploy PostgreSQL to your applications using a Helm chart from Artifact Hub. + +## Prerequisites + +Ensure you have the following tools installed: + +* **Helm**: [Installation Guide](https://helm.sh/docs/intro/install) +* **Access to Registry URL**: Obtain this from the Commands button on the Repositories page or Applications Services page + +## Deploy PostgreSQL + + + + + 1. Download the PostgreSQL Helm chart from Artifact Hub: + + ```bash + helm pull oci://registry-1.docker.io/bitnamicharts/postgresql --version 18.2.0 + ``` + + This command downloads `postgresql-18.2.0.tgz` to your local directory. + + 2. Upload the chart to your private registry: + + ```bash + helm push postgresql-18.2.0.tgz oci:///postgres --plain-http + ``` + + Replace `` with your actual registry URL (e.g., `192.168.196.42:5736`). + + **Example:** + + ```bash + helm push postgresql-18.2.0.tgz oci://192.168.196.42:5736/postgres --plain-http + ``` + + 3. After uploading, navigate to the `Applications Store` to deploy the Helm chart. + + **To allow external connections and configure storage**, adjust the deployment settings: + + ```yaml + service: + type: NodePort + port: 5432 + nodePort: 30432 # Port range: 30000-32767 + primary: + persistence: + size: 10Gi # PVC Storage Request for PostgreSQL volume (e.g., 10Gi, 20Gi, 100Gi) + ``` + + **Configuration Details**: + + * **service.type**: Set to `NodePort` to allow external connections + * **service.port**: PostgreSQL service port (default: 5432) + * **service.nodePort**: External port accessible from outside the cluster + * **primary.persistence.size**: Storage size for the PostgreSQL data volume (adjust based on your needs) + + After deployment, you can connect externally using `:`. + + 4. Retrieve the PostgreSQL password from `Applications Secrets`: + * Navigate to the **Applications Secrets** page + * Adjust the **namespace filter** in the top-right corner to select your namespace + * Click on the postgres-related secret entry + * Copy the password and decode it using base64: + ```bash + echo "" | base64 --decode + ``` + Or use this online tool: [base64decode.org](https://www.base64decode.org/) + * Use the decoded password for your PostgreSQL connections + + +## Test with Python + +You can verify your PostgreSQL deployment by using Python to perform read and write operations. + + + +### Connection Information + +Before running the test scripts, you'll need: + +* **Host**: PostgreSQL service endpoint +* **Port**: Database port (default: 5432) +* **Database**: Database name (default: postgres) +* **User**: Username (default: postgres) +* **Password**: Database password + + + + ```python + import psycopg2 + + try: + connection = psycopg2.connect( + host="", + port=5432, + database="postgres", + user="postgres", + password="" + ) + cursor = connection.cursor() + cursor.execute("SELECT version();") + version = cursor.fetchone() + print("PostgreSQL version:", version) + cursor.close() + connection.close() + print("✓ Connection successful!") + except Exception as e: + print("✗ Connection failed:", str(e)) + ``` + + + + ```python + import psycopg2 + + connection = psycopg2.connect( + host="", + port=5432, + database="postgres", + user="postgres", + password="" + ) + cursor = connection.cursor() + + # Create a test table + cursor.execute(""" + CREATE TABLE IF NOT EXISTS demo_users ( + id SERIAL PRIMARY KEY, + name VARCHAR(100), + email VARCHAR(100), + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP + ) + """) + + # Insert sample data + cursor.execute(""" + INSERT INTO demo_users (name, email) + VALUES (%s, %s) + """, ("John Doe", "john@example.com")) + + cursor.execute(""" + INSERT INTO demo_users (name, email) + VALUES (%s, %s) + """, ("Jane Smith", "jane@example.com")) + + connection.commit() + print("✓ Data inserted successfully!") + + cursor.close() + connection.close() + ``` + + + + ```python + import psycopg2 + + connection = psycopg2.connect( + host="", + port=5432, + database="postgres", + user="postgres", + password="" + ) + cursor = connection.cursor() + + # Read all data from the table + cursor.execute("SELECT id, name, email, created_at FROM demo_users") + rows = cursor.fetchall() + + print("Records in demo_users table:") + for row in rows: + print(f"ID: {row[0]}, Name: {row[1]}, Email: {row[2]}, Created: {row[3]}") + + cursor.close() + connection.close() + ``` + + + + ```python + import psycopg2 + from datetime import datetime + + class PostgreSQLDemo: + def __init__(self, host, port, database, user, password): + self.connection = psycopg2.connect( + host=host, + port=port, + database=database, + user=user, + password=password + ) + self.cursor = self.connection.cursor() + + def test_connection(self): + try: + self.cursor.execute("SELECT version();") + version = self.cursor.fetchone() + print("✓ PostgreSQL version:", version[0]) + return True + except Exception as e: + print("✗ Connection test failed:", str(e)) + return False + + def write_data(self, name, email): + try: + self.cursor.execute(""" + CREATE TABLE IF NOT EXISTS demo_users ( + id SERIAL PRIMARY KEY, + name VARCHAR(100), + email VARCHAR(100), + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP + ) + """) + self.cursor.execute(""" + INSERT INTO demo_users (name, email) VALUES (%s, %s) + """, (name, email)) + self.connection.commit() + print(f"✓ Data written: {name} ({email})") + except Exception as e: + print("✗ Write failed:", str(e)) + self.connection.rollback() + + def read_data(self): + try: + self.cursor.execute("SELECT id, name, email, created_at FROM demo_users ORDER BY id") + rows = self.cursor.fetchall() + print(f"✓ Retrieved {len(rows)} records:") + for row in rows: + print(f" ID: {row[0]}, Name: {row[1]}, Email: {row[2]}") + return rows + except Exception as e: + print("✗ Read failed:", str(e)) + return None + + def close(self): + self.cursor.close() + self.connection.close() + + # Usage + if __name__ == "__main__": + db = PostgreSQLDemo( + host="", + port=5432, + database="postgres", + user="postgres", + password="" + ) + + db.test_connection() + db.write_data("Alice Johnson", "alice@example.com") + db.write_data("Bob Wilson", "bob@example.com") + db.read_data() + db.close() + ``` + + + + diff --git a/src/content/docs/v0.6/demos/06-create-helm-chart.mdx b/src/content/docs/v0.6/demos/06-create-helm-chart.mdx new file mode 100644 index 0000000..0f3c882 --- /dev/null +++ b/src/content/docs/v0.6/demos/06-create-helm-chart.mdx @@ -0,0 +1,219 @@ +--- +title: Create Helm Chart +description: Packaging OpenBB into a Helm Chart and deploying it. +slug: v0.6/demos/06-create-helm-chart +--- + +import { Steps, Aside, Tabs, TabItem } from '@astrojs/starlight/components'; + +## About OpenBB + +The [**OpenBB Platform**](https://openbb.co/products/odp) is a unified financial data interface that simplifies API management for developers and analysts. + +**Key Benefits:** + +* **Single API Access** — Connect to multiple data providers without managing separate integrations +* **High-Quality Data** — Access reliable market data across stocks, crypto, forex, and more +* **Easy Integration** — Deploy as a containerized service for consistent environments + +## Overview + +This guide demonstrates how to containerize the OpenBB API Server using Helm charts, enabling you to deploy it consistently across Kubernetes clusters with standard deployment tools. + + + +## Prerequisites + +Before proceeding, ensure you have the following tools installed: + +* **Helm** 3.x or later — [Installation Guide](https://helm.sh/docs/intro/install) +* **Docker** — For building custom OpenBB images + +## Build Custom Docker Image + +Since the official image might be outdated, we recommend building your own Docker image from the latest source code. + + + 1. **Clone the OpenBB repository** + + Start by cloning the repository and checking out a stable version: + + ```bash + git clone https://github.com/OpenBB-finance/OpenBB.git + cd OpenBB + + # Switch to a specific version (e.g., v4.6.0) + git checkout v4.6.0 + ``` + + 2. **Build and push the Docker image** + + The OpenBB repository includes a pre-configured Dockerfile at `build/docker/platform.dockerfile`. Use this directly: + + ```bash + # Build the image with the version tag + docker build -f build/docker/platform.dockerfile -t /openbb:v4.6.0 . + ``` + + After building, push the image to your registry: + + ```bash + docker push /openbb:v4.6.0 + ``` + + + + +## Create and Package Helm Chart + + + 1. **Create a new Helm chart** + + ```bash + helm create openbb + ``` + + This generates a directory named `openbb` with the standard Helm chart structure, including templates for Deployment, Service, and ConfigMaps. + + 2. **Configure the Helm** + + Edit `openbb/Chart.yaml` to match your release metadata. You can add additional details like `icon`, `home`, and `maintainers` for better discoverability: + + ```yaml title="openbb/Chart.yaml" + apiVersion: v2 + name: openbb + description: A Helm chart for deploying the OpenBB Platform API + type: application + version: 0.1.0 + appVersion: "v4.6.0" + icon: https://raw.githubusercontent.com/OpenBB-finance/OpenBBTerminal/main/images/openbb_logo.png + home: https://openbb.co + sources: + - https://github.com/OpenBB-finance/OpenBB + maintainers: + - name: Your Name + email: your.email@example.com + ``` + + Edit `openbb/values.yaml` to configure the image and health check settings. Point the image to your custom registry image and configure probes to use `/docs` (since the root path `/` might return 404): + + ```yaml title="openbb/values.yaml" + image: + repository: /openbb + pullPolicy: IfNotPresent + tag: "v4.6.0" + + service: + type: NodePort + port: 8000 + targetPort: 8000 + nodePort: 30080 # Optional: Fixed NodePort for easier testing + + livenessProbe: + httpGet: + path: /docs # Use /docs instead of root path + port: http + + readinessProbe: + httpGet: + path: /docs # Use /docs instead of root path + port: http + ``` + + + + 3. **Package the Helm chart** + + ```bash + helm package openbb + ``` + + This creates a compressed archive: `openbb-0.1.0.tgz`. + + 4. **Push the chart to your registry** + + ```bash + helm push openbb-0.1.0.tgz oci:///charts --plain-http + ``` + + Replace `` with your actual registry address. + + Once uploaded, navigate to the [Applications Store](/v0.6/service/applications/04-store/) to deploy the chart with your custom image. + + +## Test with Python + +Once your OpenBB API Server is deployed and running, you can interact with it programmatically using Python. + +### Setup + + + +### API Interaction + +Use the following Python script to fetch data from your OpenBB API: + + + + ```python title="test_openbb_api.py" + import requests + + # Configuration + # Replace with your actual Node IP and the NodePort from values.yaml + BASE_URL = "http://:30080" + + def check_health(): + """Check if the OpenBB API server is reachable.""" + try: + response = requests.get(f"{BASE_URL}/docs") + if response.status_code == 200: + print("✓ API is online!") + return True + else: + print(f"✗ API returned status: {response.status_code}") + return False + except requests.exceptions.RequestException as e: + print(f"✗ Failed to connect: {e}") + return False + + def get_market_data(ticker="AAPL", provider="yfinance"): + """Fetch market data for a given ticker.""" + endpoint = f"{BASE_URL}/api/v1/equity/price/quote" + params = {"symbol": ticker, "provider": provider} + + try: + print(f"\nFetching {ticker} data from {provider}...") + response = requests.get(endpoint, params=params) + + if response.status_code == 200: + data = response.json() + print("✓ Data received:") + print(data) + else: + print(f"✗ Error {response.status_code}: {response.text}") + except Exception as e: + print(f"✗ Error: {e}") + + if __name__ == "__main__": + if check_health(): + get_market_data("AAPL") + # get_market_data("MSFT") + ``` + + + + diff --git a/src/content/docs/v0.6/demos/07-aidaptivcache-operator.mdx b/src/content/docs/v0.6/demos/07-aidaptivcache-operator.mdx new file mode 100644 index 0000000..dbba61e --- /dev/null +++ b/src/content/docs/v0.6/demos/07-aidaptivcache-operator.mdx @@ -0,0 +1,97 @@ +--- +title: aiDAPTIVCache Operator +description: Learn how to install the aiDAPTIVCache Operator for Phison + aiDAPTIVCache device support in Kubernetes +slug: v0.6/demos/07-aidaptivcache-operator +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +This guide demonstrates how to install the **aiDAPTIVCache Operator**, which is required for Kubernetes to recognize and utilize Phison aiDAPTIVCache devices (`phison.com/ai100`). + +## Prerequisites + +Before installing the operator, ensure you have: + +* Access to OtterScale platform with Application management permissions +* A Kubernetes cluster with Phison aiDAPTIVCache hardware installed +* Sufficient cluster resources for the operator deployment + + + +## Installation Steps + + + 1. **Navigate to Application Store** + + In the OtterScale web interface: + + * Go to **Application** → **Store** + * This opens the Helm chart repository + + 2. **Add the aiDAPTIVCache Operator Chart** + + Click **Import** button and provide the following information: + + * **Chart URL**: + ``` + https://github.com/otterscale/charts/releases/download/aidaptivcache-operator-0.4.3/aidaptivcache-operator-0.4.3.tgz + ``` + + Click **Confirm** to import the chart into your store. + + 3. **Install the Operator** + + * Find `aidaptivcache-inference` in the Store list + * Click the **Install** button + * In the Install Release dialog: + * Enter a **Name** for your deployment (e.g., `aidaptivcache-operator`) + * Enter a **Namespace** (e.g., `aidaptivcache-operator`) + * Click **View/Edit** button to open the configuration editor + + + + +## What the Operator Does + +The aiDAPTIVCache Operator performs the following functions: + +* **Resource Manager**: Manage aiDAPTIVCache devices +* **Device Discovery**: Automatically detects Phison aiDAPTIVCache devices on cluster nodes +* **Device Plugin**: Registers aiDAPTIVCache devices as Kubernetes resources, enabling targeted workload scheduling +* **Exporter**: Exposes metrics and cache information via an NVMe exporter + + + +## Troubleshooting + +### Operator Pod Not Starting + +If the operator pod fails to start: + +1. **Check pod logs via OtterScale UI**: + * Navigate to **Application** → **Workloads** + * Find the `aidaptivcache-operator` workload + * Click on the pod name to view details + * Click the **Logs** tab to view container logs + +2. Verify node labels and taints allow the operator to schedule + +3. Check that the cluster has sufficient resources + +## Next Steps + +After successfully installing the aiDAPTIVCache Operator, you can: + +* Deploy fine-tuning jobs that utilize aiDAPTIVCache devices (see [Deploy aiDAPTIVCache Finetune](/v0.6/demos/08-aidaptivcache-finetune)) +* Deploy inference services with aiDAPTIVCache acceleration (see [Deploy aiDAPTIVCache Inference](/v0.6/demos/09-aidaptivcache-inference)) + + diff --git a/src/content/docs/v0.6/demos/08-aidaptivcache-finetune.mdx b/src/content/docs/v0.6/demos/08-aidaptivcache-finetune.mdx new file mode 100644 index 0000000..e3ef0e5 --- /dev/null +++ b/src/content/docs/v0.6/demos/08-aidaptivcache-finetune.mdx @@ -0,0 +1,527 @@ +--- +title: aiDAPTIVCache Finetune +description: Fine-tune LLM models using aiDAPTIVCache in OtterScale cluster. +slug: v0.6/demos/08-aidaptivcache-finetune +--- + +import { Steps, Aside, LinkCard } from '@astrojs/starlight/components'; + +This guide demonstrates how to fine-tune Large Language Models (LLMs) using aiDAPTIVCache within the OtterScale cluster. + +## Overview + +aiDAPTIVCache finetune provides efficient model fine-tuning capabilities with support for LoRA, full parameter training, and other training modes. Key features: + +* Distributed training support (Multi-GPU) +* LoRA fine-tuning support +* Customizable training datasets +* Flexible resource allocation (vGPU, memory) + +## Prerequisites + + + +## Prepare Model and Data + +You need to make your model files accessible to the fine-tuning job. There are two methods to achieve this, both configured via the `prescript` field in the Helm chart values. + +### Method 1: Using NFS Storage (Recommended) + +This method uses OtterScale's NFS File System to store and access model files. + + + 1. **Create NFS File System in OtterScale**: + + Navigate to the Storage section: + + * Go to **Storage** → **File System** + * Create a new NFS File System or use an existing one + * Record the NFS server address (format: `10.102.197.0:/volumes/_nogroup/xxx`) + + 2. **Upload your model files to NFS**: + + Mount the NFS on a machine that has access and copy your model files: + + ```bash + # Mount NFS on a node with access + mkdir -p /mnt/nfs + mount -t nfs4 10.102.197.0:/volumes/_nogroup/xxx /mnt/nfs + + # Copy your model files to NFS + cp -r /path/to/your-model /mnt/nfs/models/ + + # Verify files + ls /mnt/nfs/models/ + ``` + + 3. **Configure prescript to mount NFS**: + + In the Helm chart values, you'll configure the `prescript` to mount this NFS (see NFS Mount Configuration section below). + + + + +### Method 2: Using SCP to Copy Models + +This method copies model files directly into the pod using SCP during initialization. + + + 1. **Prepare a remote server with model files**: + + Ensure you have a remote server (accessible from the cluster) that contains your model files. + + 2. **Configure prescript with SCP**: + + Use the following prescript template in your Helm chart values: + + ```yaml + prescript: | + # Install required tools + apt-get update && apt-get install -y sshpass + + # Create model directory + mkdir -p /mnt/data/models + + # Copy model from remote server using SCP + echo "Copying model from remote server..." + sshpass -p 'your-password' scp -o StrictHostKeyChecking=no -r \ + user@remote-host:/path/to/your-model /mnt/data/models/ + + if [ $? -eq 0 ]; then + echo "Model copied successfully!" + ls -lh /mnt/data/models/ + else + echo "Failed to copy model. Exiting..." + exit 1 + fi + ``` + + You still need an NFS mount for storing training outputs. Add NFS mount commands after the SCP section: + + ```yaml + postscript: | + # Install tools + apt-get update && apt-get install -y sshpass nfs-common + + # Copy model via SCP + mkdir -p /mnt/data/models + echo "Copying model from remote server..." + sshpass -p 'your-password' scp -o StrictHostKeyChecking=no -r \ + user@remote-host:/path/to/model /mnt/data/models/ + + # Mount NFS for output storage + mkdir -p /mnt/data/output + echo "Mounting NFS for output storage..." + mount -t nfs4 -o nfsvers=4.1 10.102.197.0:/volumes/_nogroup/output-path /mnt/data/output + + echo "Setup complete!" + ``` + + +## Install Helm Chart + + + 1. **Navigate to Application Store**: + + In the OtterScale web interface: + + * Go to **Application** → **Store** + * This opens the Helm chart repository + + 2. **Import Helm Chart**: + + * Click the **Import** button at the top of the page + * Enter the Helm Chart URL in the dialog: + ``` + https://github.com/otterscale/charts/releases/download/aidaptivcache-finetune-0.1.3/aidaptivcache-finetune-0.1.3.tgz + ``` + * Click **Confirm** to import + + 3. **Install Chart**: + + * Find `aidaptivcache-finetune` in the Store list + * Click the **Install** button + * In the Install Release dialog: + * Enter a **Name** for your deployment (e.g., `ft1`) + * Enter a **Namespace** (e.g., `ft1`) + * Click **View/Edit** button to open the configuration editor + * Edit the `values.yaml` to configure your fine-tuning job (see Configuration Guide below) + * Click **Confirm** to start the installation + + + + +## Configuration Guide + +Now that you've opened the configuration editor via **View/Edit**, you need to configure the following fields in the `values.yaml`. + +### Basic Configuration + +#### Image Settings + +```yaml +image: + repository: docker.io/library/aidaptiv + tag: vNXUN_2_05BA0 + pullPolicy: IfNotPresent +``` + +* `repository`: Container image address +* `tag`: Image version tag +* `pullPolicy`: Image pull policy (IfNotPresent/Always/Never) + +#### Job Configuration + +```yaml +job: + name: finetune-job + backoffLimit: 1 + restartPolicy: Never + ttlSecondsAfterFinished: 60 +``` + +* `name`: Kubernetes Job name +* `backoffLimit`: Number of retry attempts on failure +* `restartPolicy`: Restart policy (Never/OnFailure) +* `ttlSecondsAfterFinished`: Time to retain Job after completion (seconds) + +### Training Configuration + +The training configuration is divided into three main sections: **expConfig**, **envConfig**, and **trainDataConfig**. + +#### 1. Experiment Configuration (expConfig) + +The `expConfig` section controls GPU resources, distributed training settings, and training hyperparameters. + +**Process Settings**: + +```yaml +expConfig: + processSettings: + numGpus: 1 # Number of GPUs to use + specifyGpus: null # Specific GPU IDs (e.g., "0,1,2,3") + masterPort: 8299 # Master port for distributed training + multiNodeSettings: + enable: false # Enable multi-node training + masterAddr: "127.0.0.1" # Master node address +``` + +**Run Settings**: + +```yaml +expConfig: + runSettings: + taskType: "text-generation" # Task type + taskMode: "train" # Mode: train/eval/inference + perDeviceTrainBatchSize: 4 # Batch size per device + perUpdateTotalBatchSize: 16 # Total batch size (gradient accumulation) + numTrainEpochs: 1 # Number of training epochs + maxIter: 12 # Maximum iterations + maxSeqLen: 2048 # Maximum sequence length + triton: true # Enable Triton optimization + precisionMode: 1 # Precision mode (0: FP32, 1: Mixed) +``` + +**LoRA Settings**: + +```yaml +expConfig: + runSettings: + lora: + enableLora: false # Enable LoRA fine-tuning + loraRank: 8 # LoRA rank + loraAlpha: 16 # LoRA alpha parameter + loraTaskType: "CAUSAL_LM" # Task type for LoRA + loraTargetModules: null # Target modules (null for auto) +``` + +**Learning Rate and Optimizer**: + +```yaml +expConfig: + runSettings: + lrScheduler: + mode: 1 # LR scheduler mode + learningRate: 0.000007 # Learning rate + + optimizer: + beta1: 0.9 # Adam beta1 + beta2: 0.95 # Adam beta2 + eps: 0.00000001 # Epsilon + weightDecay: 0.01 # Weight decay +``` + +#### 2. Environment Configuration (envConfig) + +The `envConfig` section defines all file paths used during training. + +```yaml +envConfig: + pathSettings: + modelNameOrPath: "/mnt/data/models/TinyLlama-1.1B-Chat-v1.0" # Model input path + nvmePath: "/mnt/nvme0" # NVMe cache path + outputDir: "/mnt/data/output" # Training output path + trainDataPath: # Training data config + - /config/train_data/QA_dataset_config.yaml + logName: "output.log" # Log file name +``` + +**Key Path Explanations**: + +* **`modelNameOrPath`** (Required): + * Path to the pre-trained model + * Must point to where NFS mounts the model via prescript + * Example: `/mnt/data/models/TinyLlama-1.1B-Chat-v1.0` + +* **`outputDir`** (Required): + * Where fine-tuned model weights will be saved + * Must be on NFS mount for persistence: `/mnt/data/output` + +* **`nvmePath`** (Required): + * NVMe device path for temporary storage and cache + * Typically uses node's NVMe: `/mnt/nvme0` + +* **`trainDataPath`**: + * Path to training data configuration file(s) + * Supports multiple datasets (array format) + + + +#### 3. Training Data Configuration (trainDataConfig) + +The `trainDataConfig` section defines the dataset format and prompts. + +```yaml +trainDataConfig: | + instruction-dataset: + data_path: "HuggingFaceH4/instruction-dataset" # HuggingFace dataset or local path + strategy: "QA" # Data strategy (QA/Chat) + system_prompt: "A chat between a curious user and an artificial intelligence assistant." + user_prompt: "{question}" # User prompt template + question_key: "prompt" # Column name for questions + answer_key: "completion" # Column name for answers + exp_type: train # Experiment type: train/eval/inference + label_key: "completion" # Label column (same as answer_key) +``` + +**Configuration Fields**: + +* **`data_path`**: HuggingFace dataset name or local file path +* **`strategy`**: Data processing strategy (QA/Chat/Custom) +* **`system_prompt`**: System instruction for the model +* **`user_prompt`**: Template for user questions (use `{question}` placeholder) +* **`question_key`**: Dataset column containing questions +* **`answer_key`**: Dataset column containing answers +* **`exp_type`**: Must be `train` for training +* **`label_key`**: Column used as training labels (typically same as `answer_key`) + + + +### Resource Configuration + +```yaml +resources: + limits: + otterscale.com/vgpu: 1 + otterscale.com/vgpumem-percentage: 60 + phison.com/ai100: 1 + requests: + otterscale.com/vgpu: 1 + otterscale.com/vgpumem-percentage: 60 + phison.com/ai100: 1 +``` + +* `otterscale.com/vgpu`: vGPU count +* `otterscale.com/vgpumem-percentage`: vGPU memory percentage (0-100) +* `phison.com/ai100`: Phison aiDAPTIVCache accelerator count + +### NFS Mount Configuration (Required) + +To access your model files and save training outputs, you need to configure the `prescript` to mount your NFS storage. + +```yaml +prescript: | + apt install -y nfs-common + echo "Starting NFS mount process..." + mkdir -p /mnt/data + TIMEOUT=300 + ELAPSED=0 + while [ $ELAPSED -lt $TIMEOUT ]; do + echo "Attempting to mount NFS to /mnt/data" + mount -t nfs4 -o nfsvers=4.1 -v 10.102.197.0:/volumes/_nogroup/your-nfs-path /mnt/data + if mountpoint -q /mnt/data; then + echo "NFS mount successful!" + break + else + echo "Mount failed, retrying in 5 seconds... (${ELAPSED}s/${TIMEOUT}s)" + sleep 5 + ELAPSED=$((ELAPSED + 5)) + fi + done + if [ $ELAPSED -ge $TIMEOUT ]; then + echo "NFS mount timeout after ${TIMEOUT} seconds. Exiting..." + exit 1 + fi +``` + +**Configuration Details**: + +* Replace `10.102.197.0:/volumes/_nogroup/your-nfs-path` with your actual NFS server address from the File System page +* The script installs `nfs-common` package (required for NFS mounting) +* Implements retry logic with a 5-minute timeout +* Mounts NFS to `/mnt/data` which is used in the path configuration + +**Optional Post-execution Script**: + +```yaml +postscript: | + echo "Training job completed" + echo "Model saved to: $outputDir" +``` + + + +## Complete Configuration Example + +```yaml +image: + repository: docker.io/library/aidaptiv + tag: vNXUN_2_05BA0 + pullPolicy: IfNotPresent + +job: + name: finetune-llama-job + backoffLimit: 1 + restartPolicy: Never + ttlSecondsAfterFinished: 60 + +securityContext: + privileged: true + +# NFS Mount Script (Required) +prescript: | + apt install -y nfs-common + echo "Starting NFS mount process..." + mkdir -p /mnt/data + TIMEOUT=300 + ELAPSED=0 + while [ $ELAPSED -lt $TIMEOUT ]; do + echo "Attempting to mount NFS to /mnt/data" + mount -t nfs4 -o nfsvers=4.1 -v 10.102.197.0:/volumes/_nogroup/my-nfs-path /mnt/data + if mountpoint -q /mnt/data; then + echo "NFS mount successful!" + break + else + echo "Mount failed, retrying in 5 seconds... (${ELAPSED}s/${TIMEOUT}s)" + sleep 5 + ELAPSED=$((ELAPSED + 5)) + fi + done + if [ $ELAPSED -ge $TIMEOUT ]; then + echo "NFS mount timeout after ${TIMEOUT} seconds. Exiting..." + exit 1 + fi + +envConfig: + pathSettings: + modelNameOrPath: "/mnt/data/models/TinyLlama-1.1B-Chat-v1.0" + nvmePath: "/mnt/nvme0" + outputDir: "/mnt/data/output" + trainDataPath: + - /config/train_data/QA_dataset_config.yaml + logName: "finetune_output.log" + +expConfig: + processSettings: + numGpus: 1 + masterPort: 8299 + multiNodeSettings: + enable: false + + runSettings: + taskType: "text-generation" + taskMode: "train" + perDeviceTrainBatchSize: 4 + perUpdateTotalBatchSize: 16 + numTrainEpochs: 1 + maxIter: 100 + maxSeqLen: 2048 + triton: true + + lrScheduler: + mode: 1 + learningRate: 0.000007 + + lora: + enableLora: true + loraRank: 8 + loraAlpha: 16 + loraTaskType: "CAUSAL_LM" + +trainDataConfig: | + instruction-dataset: + data_path: "HuggingFaceH4/instruction-dataset" + strategy: "QA" + system_prompt: "A chat between a curious user and an artificial intelligence assistant." + user_prompt: "{question}" + question_key: "prompt" + answer_key: "completion" + exp_type: train + label_key: "completion" + +resources: + limits: + otterscale.com/vgpu: 1 + otterscale.com/vgpumem-percentage: 60 + phison.com/ai100: 1 + requests: + otterscale.com/vgpu: 1 + otterscale.com/vgpumem-percentage: 60 + phison.com/ai100: 1 +``` + +## Monitor Training Progress + + + 1. **Check Job Status**: + + Navigate to the Jobs page: + + * Go to **Applications** → **Jobs** + * Find your fine-tune job under your namespace and check its status. + + 2. **Retrieve Output Model**: + + After training completes, the fine-tuned model will be saved in the path specified by `outputDir`: + + ```bash + # Access via the same NFS mount used during training + # Mount the NFS on your local machine or a node + mount -t nfs4 10.102.197.0:/volumes/_nogroup/your-nfs-path /mnt/nfs + ls /mnt/nfs/output/ + ``` + + +## Related Resources + + + + diff --git a/src/content/docs/v0.6/demos/09-aidaptivcache-inference.mdx b/src/content/docs/v0.6/demos/09-aidaptivcache-inference.mdx new file mode 100644 index 0000000..f6f90f7 --- /dev/null +++ b/src/content/docs/v0.6/demos/09-aidaptivcache-inference.mdx @@ -0,0 +1,596 @@ +--- +title: aiDAPTIVCache Inference +description: Deploy high-performance LLM inference service using aiDAPTIV Cache. +slug: v0.6/demos/09-aidaptivcache-inference +--- + +import { Steps, Aside, LinkCard } from '@astrojs/starlight/components'; + +This guide demonstrates how to deploy a high-performance LLM inference service using aiDAPTIV Cache within the OtterScale cluster. + +## Overview + +aiDAPTIVCache Inference provides high-performance LLM inference service based on vLLM, supporting: + +* High-throughput serving +* Tensor parallelism (Multi-GPU) +* KV Cache offloading +* Dynamic LoRA loading +* OpenAI-compatible API + +## Prerequisites + + + +## Prepare Model + +You need to make your model files accessible to the inference service. There are two methods to achieve this, both configured via the `prescript` field in the Helm chart values. + +### Method 1: Using NFS Storage (Recommended) + +This method uses OtterScale's NFS File System to store and access model files. + + + 1. **Create NFS File System in OtterScale**: + + Navigate to the Storage section: + + * Go to **Storage** → **File System** + * Create a new NFS File System or use an existing one + * Record the NFS server address (format: `10.102.197.0:/volumes/_nogroup/xxx`) + + 2. **Upload your model files to NFS**: + + Mount the NFS on a machine that has access and copy your model files: + + ```bash + # Mount NFS on a node with access + mkdir -p /mnt/nfs + mount -t nfs4 10.102.197.0:/volumes/_nogroup/xxx /mnt/nfs + + # Copy your model files to NFS + cp -r /path/to/your-model /mnt/nfs/models/ + + # Verify files + ls /mnt/nfs/models/ + ``` + + 3. **Configure prescript to mount NFS**: + + In the Helm chart values, you'll configure the `prescript` to mount this NFS (see NFS Mount Configuration section below). + + + + +### Method 2: Using SCP to Copy Models + +This method copies model files directly into the pod using SCP during initialization. + + + 1. **Prepare a remote server with model files**: + + Ensure you have a remote server (accessible from the cluster) that contains your model files. + + 2. **Configure prescript with SCP**: + + Use the following prescript template in your Helm chart values: + + ```yaml + prescript: | + # Install required tools + apt-get update && apt-get install -y sshpass + + # Create model directory + mkdir -p /mnt/data/models + + # Copy model from remote server using SCP + echo "Copying model from remote server..." + sshpass -p 'your-password' scp -o StrictHostKeyChecking=no -r \ + user@remote-host:/path/to/your-model /mnt/data/models/ + + if [ $? -eq 0 ]; then + echo "Model copied successfully!" + ls -lh /mnt/data/models/ + else + echo "Failed to copy model. Exiting..." + exit 1 + fi + ``` + + +## Install Helm Chart + + + 1. **Navigate to Application Store**: + + In the OtterScale web interface: + + * Go to **Application** → **Store** + * This opens the Helm chart repository + + 2. **Import Helm Chart**: + + * Click the **Import** button at the top of the page + * Enter the Helm Chart URL in the dialog: + ``` + https://github.com/otterscale/charts/releases/download/aidaptivcache-inference-0.1.3/aidaptivcache-inference-0.1.3.tgz + ``` + * Click **Confirm** to import + + 3. **Install Chart**: + + * Find `aidaptivcache-inference` in the Store list + * Click the **Install** button + * In the Install Release dialog: + * Enter a **Name** for your deployment (e.g., `llama-inference`) + * Enter a **Namespace** (e.g., `inference`) + * Click **View/Edit** button to open the configuration editor + * Edit the `values.yaml` to configure your inference service (see Configuration Guide below) + * Click **Confirm** to start the installation + + + + +## Configuration Guide + +Now that you've opened the configuration editor via **View/Edit**, you need to configure the following fields in the `values.yaml`. + +### Basic Configuration + +#### Image Settings + +```yaml +image: + repository: docker.io/library/aidaptiv + tag: vNXUN_3_03AA + pullPolicy: IfNotPresent +``` + +* `repository`: Container image address +* `tag`: Image version tag +* `pullPolicy`: Image pull policy (IfNotPresent/Always/Never) + +#### Deployment Configuration + +```yaml +deployment: + name: vllm-api + replicas: 1 +``` + +* `name`: Kubernetes Deployment name +* `replicas`: Number of Pod replicas (typically 1 due to limited GPU resources) + +### vLLM Configuration + +#### Environment Variables + +```yaml +vllm: + env: + vllmUseV1: "1" + vllmWorkerMultiprocMethod: "spawn" + tiktokenEncodingsBase: "" +``` + +* `vllmUseV1`: Use vLLM v1 API +* `vllmWorkerMultiprocMethod`: Multi-process startup method (spawn/fork) + +#### Command Line Arguments (Important) + +```yaml +vllm: + args: + model: /mnt/data/model/Meta-Llama-3.1-8B-Instruct/ + nvmePath: /mnt/nvme0 + port: 8000 + gpuMemoryUtilization: 0.9 + maxModelLen: 32768 + tensorParallelSize: 4 + dramKvOffloadGb: 0 + ssdKvOffloadGb: 500 + noResumeKvCache: true + disableGpuReuse: false + enableChunkedPrefill: true +``` + +**Key Parameter Explanations**: + +* **`model`** (required): + * Model input path + * Must correspond to the container mount path + * Example: `/mnt/data/model/Meta-Llama-3.1-8B-Instruct/` + * **Note**: This is the container path, not the NFS server path! + +* **`nvmePath`** (required): + * NVMe cache path + * Used for KV Cache offloading + * Typically uses node NVMe: `/mnt/nvme0` + +* **`port`**: + * vLLM API service port + * Default 8000 + +* **`gpuMemoryUtilization`**: + * GPU memory utilization ratio (0.0-1.0) + * Recommended 0.8-0.9 to reserve some memory buffer + +* **`maxModelLen`**: + * Maximum sequence length + * Adjust based on model and GPU memory + +* **`tensorParallelSize`**: + * Number of GPUs for tensor parallelism + * Must match the `otterscale.com/vgpu` value in resource configuration + * Example: If `tensorParallelSize: 4`, you must set `otterscale.com/vgpu: 4` + +* **`dramKvOffloadGb`**: + * KV Cache offload to DRAM capacity (GB) + * Set to 0 to disable DRAM offload + +* **`ssdKvOffloadGb`**: + * KV Cache offload to SSD capacity (GB) + * Used with `nvmePath` + +* **`enableChunkedPrefill`**: + * Enable chunked prefill for better long-text performance + +**Optional Parameters** (commented by default): + +```yaml +# disableLongToken: true # Disable long token support +# resumeKvCache: true # Resume KV Cache +# cleanObsoleteKvCache: true # Clean obsolete KV Cache +# enablePrefixCaching: true # Enable prefix caching +# enforceEager: true # Force eager mode +``` + +#### LoRA Configuration + +```yaml +vllm: + lora: + enable: false + modules: "" + maxRank: 32 +``` + +**Enable LoRA Example**: + +```yaml +vllm: + lora: + enable: true + modules: "lora=/mnt/data/lora-adapters/llama3.1-8B-lora/" + maxRank: 32 +``` + +* `enable`: Set to `true` to enable LoRA +* `modules`: LoRA adapter path, format: `lora=/path/to/adapter/` +* `maxRank`: Maximum LoRA rank + +**Note**: All three parameters must be configured together to enable LoRA. + +### NFS Mount Configuration (For Method 1) + +If you're using NFS storage to access your model files, configure the `prescript` to mount your NFS storage. + +```yaml +prescript: | + apt install -y nfs-common + echo "Starting NFS mount process..." + mkdir -p /mnt/data + TIMEOUT=300 + ELAPSED=0 + while [ $ELAPSED -lt $TIMEOUT ]; do + echo "Attempting to mount NFS to /mnt/data" + mount -t nfs4 -o nfsvers=4.1 -v 10.102.197.0:/volumes/_nogroup/your-nfs-path /mnt/data + if mountpoint -q /mnt/data; then + echo "NFS mount successful!" + break + else + echo "Mount failed, retrying in 5 seconds... (${ELAPSED}s/${TIMEOUT}s)" + sleep 5 + ELAPSED=$((ELAPSED + 5)) + fi + done + if [ $ELAPSED -ge $TIMEOUT ]; then + echo "NFS mount timeout after ${TIMEOUT} seconds. Exiting..." + exit 1 + fi +``` + +**Configuration Details**: + +* Replace `10.102.197.0:/volumes/_nogroup/your-nfs-path` with your actual NFS server address from the File System page +* The script installs `nfs-common` package (required for NFS mounting) +* Implements retry logic with a 5-minute timeout +* Mounts NFS to `/mnt/data` which is used in the model path configuration + + + +### Service Configuration + +```yaml +service: + type: NodePort + port: 8000 + targetPort: 8000 + # nodePort: 30299 +``` + +* `type`: Service type (NodePort/ClusterIP/LoadBalancer) +* `port`: Service external port +* `targetPort`: Container internal port +* `nodePort`: (Optional) Specify a fixed NodePort + +### Volume Configuration + +```yaml +volumes: + dshm: + enabled: true + sizeLimit: 30Gi +``` + +* **`dshm`**: + * `enabled`: Enable /dev/shm (shared memory) + * `sizeLimit`: Shared memory size (required for vLLM) + + + +### Resource Configuration + +```yaml +resources: + requests: + otterscale.com/vgpu: 1 + otterscale.com/vgpumem-percentage: 60 + phison.com/ai100: 1 + limits: + otterscale.com/vgpu: 1 + otterscale.com/vgpumem-percentage: 60 + phison.com/ai100: 1 +``` + +* **`otterscale.com/vgpu`**: vGPU count + * Must match `vllm.args.tensorParallelSize` for multi-GPU deployment + * Example: For 4-GPU tensor parallelism, set both `tensorParallelSize: 4` and `otterscale.com/vgpu: 4` +* **`otterscale.com/vgpumem-percentage`**: vGPU memory percentage (0-100) +* **`otterscale.com/vgpumem`**: Alternative to percentage, directly specify memory amount (MB) +* **`phison.com/ai100`**: Phison aiDAPTIVCache accelerator count + + + +## Complete Configuration Examples + +### Example: Basic Inference Service + +```yaml +image: + repository: docker.io/library/aidaptiv + tag: vNXUN_3_03AA + pullPolicy: IfNotPresent + +deployment: + name: llama3-inference + replicas: 1 + +vllm: + env: + vllmUseV1: "1" + vllmWorkerMultiprocMethod: "spawn" + + args: + model: /mnt/data/model/Meta-Llama-3.1-8B-Instruct/ + nvmePath: /mnt/nvme0 + port: 8000 + gpuMemoryUtilization: 0.9 + maxModelLen: 32768 + tensorParallelSize: 1 + ssdKvOffloadGb: 500 + enableChunkedPrefill: true + + lora: + enable: false + +service: + type: NodePort + port: 8000 + targetPort: 8000 + +securityContext: + privileged: true + +# NFS Mount Script +prescript: | + apt install -y nfs-common + echo "Starting NFS mount process..." + mkdir -p /mnt/data + TIMEOUT=300 + ELAPSED=0 + while [ $ELAPSED -lt $TIMEOUT ]; do + echo "Attempting to mount NFS to /mnt/data" + mount -t nfs4 -o nfsvers=4.1 -v 10.102.197.0:/volumes/_nogroup/models /mnt/data + if mountpoint -q /mnt/data; then + echo "NFS mount successful!" + break + else + echo "Mount failed, retrying in 5 seconds... (${ELAPSED}s/${TIMEOUT}s)" + sleep 5 + ELAPSED=$((ELAPSED + 5)) + fi + done + if [ $ELAPSED -ge $TIMEOUT ]; then + echo "NFS mount timeout after ${TIMEOUT} seconds. Exiting..." + exit 1 + fi + +volumes: + dshm: + enabled: true + sizeLimit: 30Gi + +resources: + requests: + otterscale.com/vgpu: 1 + otterscale.com/vgpumem-percentage: 80 + phison.com/ai100: 1 + limits: + otterscale.com/vgpu: 1 + otterscale.com/vgpumem-percentage: 80 + phison.com/ai100: 1 +``` + +## Using the Inference Service + + + 1. **Get Service Address**: + + * Go to **Application** → **Services** + * Find your inference service and note the NodePort. + + 2. **Test API Connection**: + + ```bash + # Get Node IP + NODE_IP="your-node-ip" + NODE_PORT="your-node-port" + + # Test health check + curl http://${NODE_IP}:${NODE_PORT}/health + ``` + + 3. **Use OpenAI-Compatible API**: + + ```bash + curl http://${NODE_IP}:${NODE_PORT}/v1/completions \ + -H "Content-Type: application/json" \ + -d '{ + "model": "Meta-Llama-3.1-8B-Instruct", + "prompt": "What is the capital of France?", + "max_tokens": 100, + "temperature": 0.7 + }' + ``` + + 4. **Use Chat Completions API**: + + ```bash + curl http://${NODE_IP}:${NODE_PORT}/v1/chat/completions \ + -H "Content-Type: application/json" \ + -d '{ + "model": "Meta-Llama-3.1-8B-Instruct", + "messages": [ + {"role": "system", "content": "You are a helpful assistant."}, + {"role": "user", "content": "What is machine learning?"} + ], + "max_tokens": 200 + }' + ``` + + 5. **Python Client Example**: + + ```python + from openai import OpenAI + + # Connect to vLLM service + client = OpenAI( + base_url=f"http://{NODE_IP}:{NODE_PORT}/v1", + api_key="dummy" # vLLM doesn't require a real API key + ) + + # Perform inference + response = client.chat.completions.create( + model="Meta-Llama-3.1-8B-Instruct", + messages=[ + {"role": "user", "content": "Explain quantum computing in simple terms"} + ], + max_tokens=150, + temperature=0.8 + ) + + print(response.choices[0].message.content) + ``` + + +## Monitoring and Debugging + + + 1. **Check Deployment Status**: + + Navigate to the Workloads page: + + * Go to **Application** → **Workloads** + * Find your deployment + + 2. **View Pod Logs**: + + * Click on the Pod corresponding to the Deployment + * View the **Logs** tab + * Monitor model loading, inference requests, etc. + + 3. **Check Resource Usage**: + + * View GPU and memory usage in the Pod details page + * Check for OOM (Out of Memory) errors + + +## Performance Tuning Recommendations + +### Memory Optimization + +* **Small models** (\< 7B): + * `gpuMemoryUtilization: 0.9` + * `ssdKvOffloadGb: 0` (no offload needed) + +* **Medium models** (7B-13B): + * `gpuMemoryUtilization: 0.85` + * `ssdKvOffloadGb: 200-500` + +* **Large models** (> 13B): + * `gpuMemoryUtilization: 0.8` + * `ssdKvOffloadGb: 500-1000` + * Consider multi-GPU: `tensorParallelSize: 2-4` with `otterscale.com/vgpu: 2-4` + +### Latency vs Throughput Trade-off + +* **Low latency priority**: + ```yaml + maxModelLen: 8192 # Shorter sequences + enableChunkedPrefill: false + dramKvOffloadGb: 0 + ssdKvOffloadGb: 0 + ``` + +* **High throughput priority**: + ```yaml + maxModelLen: 32768 # Longer sequences + enableChunkedPrefill: true + enablePrefixCaching: true + ssdKvOffloadGb: 500 + ``` + +## Related Resources + + + + + + diff --git a/src/content/docs/v0.6/getting-started/01-prerequisites.mdx b/src/content/docs/v0.6/getting-started/01-prerequisites.mdx new file mode 100644 index 0000000..1840d04 --- /dev/null +++ b/src/content/docs/v0.6/getting-started/01-prerequisites.mdx @@ -0,0 +1,222 @@ +--- +title: Prerequisites +description: Hardware and network requirements for running OtterScale. +slug: v0.6/getting-started/01-prerequisites +--- + +import { Card, CardGrid, Aside, Badge } from '@astrojs/starlight/components'; + + + +## OtterScale Control Node + +The Control Node serves as the central management hub for your OtterScale deployment. Before proceeding with installation, verify that your designated control node machine meets the following requirements. + +### Operating System + +Install Ubuntu 24.04 LTS on your control node. If your machine runs a different OS, perform a clean installation of Ubuntu 24.04 LTS first. + +| Component | Requirement | +| :-------- | :------------------------------ | +| **OS** | **Ubuntu 24.04 LTS** (Required) | + +### Hardware Requirements + +Ensure your control node hardware meets or exceeds these minimum specifications. Higher resources will improve performance and stability. + +| Resource | Minimum Requirement | +| :------------- | :----------------------- | +| **CPU** | 8 Cores | +| **Memory** | 16 GB RAM | +| **Disk Space** | 100 GB available storage | + +### Network Configuration + +The OtterScale installer will automatically configure networking, but confirm the following prerequisites: + +* **Connectivity:** Ensure at least one network interface has external internet access. +* **Bridge Configuration:** The installer checks for a network bridge named `br-otters`. + * If it exists, the installer will use it. + * If not, you will be prompted to select an existing bridge or allow the installer to create one automatically. + +*** + + + +## K8S Nodes (Server Nodes) + +K8S nodes are the servers that will form your Kubernetes cluster. These nodes must be commissioned via the OtterScale web interface after creating a Scope, and then provisioned. Ensure each server host is configured as follows before commissioning. + +### BIOS Configuration + +Access your server's BIOS settings (typically by pressing F2, F10, or Del during boot) and configure the following settings: + +1. **BMC Settings:** + * **BMC Static IP:** Assign a static IP address to the BMC for reliable remote management access. + * **Boot Order:** Enable network boot via BMC and set it as the highest priority in the boot order. +2. **Boot Options:** + * **Boot Mode:** Set to **UEFI** (recommended for modern deployments). + * Avoid Legacy mode, as it limits drive size to 2TB, lacks security features, and does not support GPT partitioning. + * **Fast Boot:** Disable Fast Boot to allow complete hardware initialization. +3. **CPU Virtualization:** + * **Intel CPUs:** Enable `VMX`, `VT-d`, or `VT-x`. + * **AMD CPUs:** Enable `SVM` or `AMD-V`. + +### Hardware Requirements + +Verify that each K8S node meets these storage requirements for optimal performance. + +| Resource | Minimum Requirement | +| :---------- | :-------------------------------------------------- | +| **Storage** | At least **2 Block disks** or **2 Physical drives** | + +*** + +## Network IP Requirement + +Plan your network IP allocation carefully to prevent conflicts. Ensure your subnet has sufficient available IP addresses for the OtterScale deployment. + +| Usage | Quantity | Description | +| :---------------------- | :------- | :----------------------------------------------------------------------------- | +| **OS System** | 1 | Reserved for the ingress controller. | +| **OtterScale** | 1 | Required from user. A second IP in the same subnet for OtterScale services. | +| **Juju Controller** | 1 | Used by the Canonical Juju controller. | +| **MAAS (DHCP)** | 2 | Used for MAAS dynamic IP allocation. | +| **Kubernetes and Ceph** | 9 + N | Used for Kubernetes and Ceph services (N = number of K8S nodes). | + +**Total Estimated IPs:** 14 + N (where N is the number of K8S nodes) + +*** + + + +## Firewall Configuration + +The OtterScale installation process requires outbound internet access to various external services. Configure your firewall to allow outbound connections to the following domains and ports on all nodes (Control Node and K8S nodes). + +
+ Canonical + + | Domains | Port(s) | + | :------------------------------ | :-------------- | + | `api.charmhub.io` | TCP 443 (HTTPS) | + | `api.jujucharms.com` | TCP 443 (HTTPS) | + | `changelogs.ubuntu.com` | TCP 443 (HTTPS) | + | `charmhub.io` | TCP 443 (HTTPS) | + | `cloud-images.ubuntu.com` | TCP 443 (HTTPS) | + | `maas.ubuntu.com` | TCP 443 (HTTPS) | + | `images.maas.io` | TCP 443 (HTTPS) | + | `juju.is` | TCP 443 (HTTPS) | + | `jaas.ai` | TCP 443 (HTTPS) | + | `streams.canonical.com` | TCP 443 (HTTPS) | + | `objects.githubusercontent.com` | TCP 443 (HTTPS) | + | `contracts.canonical.com` | TCP 443 (HTTPS) | + | `images.maas.io` | TCP 80 (HTTP) | +
+ +
+ Snap Package + + | Domains | Port(s) | + | :----------------------------------------- | :-------------- | + | `snapcraft.io` | TCP 443 (HTTPS) | + | `api.snapcraft.io` | TCP 443 (HTTPS) | + | `storage.snapcraftcontent.com` | TCP 443 (HTTPS) | + | `canonical-lgw01.cdn.snapcraftcontent.com` | TCP 443 (HTTPS) | + | `canonical-lcy01.cdn.snapcraftcontent.com` | TCP 443 (HTTPS) | + | `canonical-lcy02.cdn.snapcraftcontent.com` | TCP 443 (HTTPS) | + | `canonical-bos01.cdn.snapcraftcontent.com` | TCP 443 (HTTPS) | +
+ +
+ Ubuntu Repositories + + | Domains | Port(s) | + | :---------------------- | :-------------------------------- | + | `tw.archive.ubuntu.com` | TCP 443 (HTTPS)
TCP 80 (HTTP) | + | `archive.ubuntu.com` | TCP 443 (HTTPS)
TCP 80 (HTTP) | + | `ports.ubuntu.com` | TCP 443 (HTTPS)
TCP 80 (HTTP) | + | `security.ubuntu.com` | TCP 443 (HTTPS)
TCP 80 (HTTP) | + | `esm.ubuntu.com` | TCP 443 (HTTPS)
TCP 80 (HTTP) | +
+ +
+ GitHub + + | Domains | Port(s) | + | :------------------------------------- | :-------------- | + | `github.com` | TCP 443 (HTTPS) | + | `raw.githubusercontent.com` | TCP 443 (HTTPS) | + | `release-assets.githubusercontent.com` | TCP 443 (HTTPS) | +
+ +
+ Kubernetes + + | Domains | Port(s) | + | :----------------------------------------------------------------------------- | :-------------- | + | `registry.k8s.io` | TCP 443 (HTTPS) | + | `k8s.gcr.io` | TCP 443 (HTTPS) | + | `ghcr.io` | TCP 443 (HTTPS) | + | `coredns` | TCP 443 (HTTPS) | + | `d39mqg4b1dx9z1.cloudfront.net` | TCP 443 (HTTPS) | + | `storage.googleapis.com` | TCP 443 (HTTPS) | + | `nvcr.io` | TCP 443 (HTTPS) | + | `auth.docker.io` | TCP 443 (HTTPS) | + | `auth.docker.com` | TCP 443 (HTTPS) | + | `login.docker.com` | TCP 443 (HTTPS) | + | `cdn.auth0.com` | TCP 443 (HTTPS) | + | `docker.io` | TCP 443 (HTTPS) | + | `hub.docker.com` | TCP 443 (HTTPS) | + | `registry-1.docker.io` | TCP 443 (HTTPS) | + | `index.docker.io` | TCP 443 (HTTPS) | + | `production.cloudflare.docker.com` | TCP 443 (HTTPS) | + | `docker-images-prod.6aa30f8b08e16409b46e0173d6de2f56.r2.cloudflarestorage.com` | TCP 443 (HTTPS) | + | `registry.cn-hangzhou.aliyuncs.com` | TCP 443 (HTTPS) | +
+ +
+ HuggingFace + + | Domains | Port(s) | + | :----------------------- | :-------------- | + | `huggingface.co` | TCP 443 (HTTPS) | + | `cdn-lfs.huggingface.co` | TCP 443 (HTTPS) | + | `cdn.huggingface.co` | TCP 443 (HTTPS) | +
+ +
+ RedHat Models + + | Domains | Port(s) | + | :--------------------------- | :-------------- | + | `registry.redhat.io` | TCP 443 (HTTPS) | + | `quay.io` | TCP 443 (HTTPS) | + | `registry.access.redhat.com` | TCP 443 (HTTPS) | +
+ +
+ HELM Charts + + | Domains | Port(s) | Description | + | :------------------------------------- | :-------------- | :------------ | + | `otterscale.github.io` | TCP 443 (HTTPS) | #OtterScale | + | `charts.jetstack.io` | TCP 443 (HTTPS) | #Cert-manager | + | `open-feature.github.io` | TCP 443 (HTTPS) | #Open-feature | + | `istio-release.storage.googleapis.com` | TCP 443 (HTTPS) | #Istio | + | `prometheus-community.github.io` | TCP 443 (HTTPS) | #prometheus | + | `project-hami.github.io` | TCP 443 (HTTPS) | #HAMi | + | `helm.ngc.nvidia.com` | TCP 443 (HTTPS) | #Nvidia | + | `cloudnative-pg.github.io/charts` | TCP 443 (HTTPS) | #CloudNative | + | `llm-d.ai` | TCP 443 (HTTPS) | #llm-d | + | `codecentric.github.io` | TCP 443 (HTTPS) | #KeyCloak | + | `charts.bitnami.com` | TCP 443 (HTTPS) | #Bitnami | +
diff --git a/src/content/docs/v0.6/getting-started/02-installation.mdx b/src/content/docs/v0.6/getting-started/02-installation.mdx new file mode 100644 index 0000000..4039d38 --- /dev/null +++ b/src/content/docs/v0.6/getting-started/02-installation.mdx @@ -0,0 +1,81 @@ +--- +title: Installation +description: Step-by-step guide to installing OtterScale. +slug: v0.6/getting-started/02-installation +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +This guide provides a detailed, step-by-step process for installing OtterScale on your Control Node. Ensure you have completed all prerequisites outlined in the Prerequisites section before proceeding. The installation involves setting up dependencies, configuring the environment, and deploying the system. + + + + + 1. ### **Install Required Packages and Docker** + + Install essential tools and Docker, which are needed for cloning the repository and running containerized services. + + ```bash + sudo apt update + sudo apt install -y git curl + sudo snap install docker + ``` + + 2. ### **Clone the OtterScale Repository** + + Download the OtterScale source code from GitHub. + + ```bash + git clone https://github.com/otterscale/otterscale.git + ``` + + 3. ### **Configure the Environment File** + + Navigate to the cloned directory and set up the environment configuration. + + ```bash + cd otterscale + cp .env.example .env + ``` + + Edit the `.env` file to update the following variables: + + * `APP_VERSION`: Set to the desired version (e.g., `0.6.0`). + * `PUBLIC_API_URL`: Set to your Control Node's IP address and port (e.g., `http://192.168.1.100:8299`). Replace `xx.xx.xx.xx` with your actual IP. + + You can edit the file using a text editor like `nano`: + + ```bash + nano .env + ``` + + 4. ### **Start OtterScale Services** + + Launch the necessary services in the background using Docker Compose. + + ```bash + sudo docker-compose up -d + ``` + + Verify that the services are running: + + ```bash + sudo docker-compose ps + ``` + + 5. ### **Execute the Installation Script** + + Complete the installation via the web interface. + + 1. Open your web browser and access the OtterScale UI at the `PUBLIC_API_URL` you configured (e.g., `http://192.168.1.100:8299`). + 2. In the UI, locate and copy the installation CLI command. + 3. Paste and run the command in your terminal with sudo privileges. + + If you encounter any issues during execution, first verify your Firewall Configuration as outlined in the Prerequisites section. Additionally, check the `setup.log` file in the current directory for detailed error information. + + + diff --git a/src/content/docs/v0.6/getting-started/03-scope.mdx b/src/content/docs/v0.6/getting-started/03-scope.mdx new file mode 100644 index 0000000..be860bf --- /dev/null +++ b/src/content/docs/v0.6/getting-started/03-scope.mdx @@ -0,0 +1,107 @@ +--- +title: Scope +description: Manage scopes in OtterScale. +slug: v0.6/getting-started/03-scope +--- + +import { Steps } from '@astrojs/starlight/components'; +import { Aside } from '@astrojs/starlight/components'; +import { Icon } from '@astrojs/starlight/components'; + +Scopes allow you to organize your resources and control access. + +## Selecting a Scope + +You can select a scope from the dropdown menu in the navigation bar. This will filter the resources you see to only those within the selected scope. + +## Creating a Scope + +To create a new scope, navigate to the Scope management area and click on "Create Scope". A side panel will appear with the creation form. + + + 1. **Select a Plan** + + At the top of the form, you will see the details of the plan associated with the scope you are creating. Different plans support different features: + + | Feature | Standard | Advanced | Enterprise | + | :--------- | :---------------------------- | :---------------------------- | :---------------------------- | + | Ceph | | | | + | Kubernetes | | | | + | Cluster | | | | + | Node | Single-Node | Multi-Node | Multi-Node | + + 2. **Configure Scope Details** + + Fill in the following information to configure your new scope: + + * **Scope Name**: Enter a unique name for your scope. + * **Machine**: Select the physical machine to assign to this scope. + + * **Storage Devices**: Select the block devices to be used. (Appears after selecting a machine). + + * **Network Configuration** (Optional): + * **Calico CIDR**: The CIDR block for Calico networking (e.g., `192.168.0.0/16`). + * **Virtual IP**: The virtual IP address for the scope (e.g., `192.168.1.1`). + + 3. **Create Scope** + + Once you have filled in the details, click the **Create** button to initiate the creation process. + + +## Automated Provisioning + +After you initiate the creation, the system automatically performs the following steps: + + + 1. **Create Scope**: Initializes the scope record. + + This step maps to the Juju `CreateModel` operation. It establishes a new isolated workspace (Model) within the Juju controller. Key actions include: + + * **Namespace Isolation**: Creates a logical boundary for resources, ensuring that applications and machines in this scope do not interfere with others. + * **Environment Configuration**: Sets up model-level configurations, such as APT mirrors for faster package downloads. + * **Access Control**: Automatically injects SSH keys to grant authorized users access to the machines within this scope. + + 2. **Add Machine Tags**: Tags the selected machine. + + This step applies specific tags to the machine in MAAS. Tags are used to: + + * **Mark Ownership**: Associates the machine with the specific scope being created. + * **Reserve Resources**: Prevents other processes from accidentally using this machine while it is being set up. + * **Define Capabilities**: Can be used to indicate specific hardware capabilities or roles (e.g., `compute`, `storage`) required for the node. + + 3. **Commission Machine**: Configures the machine (SSH, networking, storage). + + Commissioning is a critical step to verify hardware and prepare it for deployment. It involves: + + * **Hardware Inventory**: Boots an ephemeral OS to scan and record detailed specs (CPU, Memory, Disks, NICs). + * **Health Checks**: Runs scripts to test hardware functionality (Disk I/O, Memory, IPMI/BMC). + * **Configuration**: Sets up out-of-band management (BMC/IPMI) and registers network/storage interfaces. + * **Status Change**: On success, the machine becomes `Ready` for deployment. On failure, it is marked as `Failed commissioning` for troubleshooting. + + 4. **Create Machine**: Associates the machine with the scope. + + This step executes the Juju `AddMachines` operation. It registers the specific physical machine (from MAAS) into the Juju controller. This action triggers: + + * **Provisioning**: Juju instructs MAAS to deploy the operating system (e.g., Ubuntu) onto the machine. + * **Agent Installation**: Once the OS is running, the Juju Agent is installed, allowing Juju to manage the machine as a node. + + 5. **Create Node**: Finalizes the node creation with network and storage settings. + + This is the final orchestration step where the actual software stack is deployed. It performs the following actions: + + * **Network Reservation**: Reserves necessary IP addresses for internal services (e.g., Ceph NFS, Kubernetes Load Balancer). + * **Software Deployment**: Deploys and configures the core components: + * **Ceph**: For distributed storage (using the selected OSD devices). + * **Kubernetes**: For container orchestration (configuring Calico networking and Load Balancers). + * **Addons**: Additional system utilities. + * **Observability (COS)**: Monitoring and logging stack. + * **Relation Establishment**: Connects these components together to ensure they work as a cohesive system. + + + diff --git a/src/content/docs/v0.6/guides/example.md b/src/content/docs/v0.6/guides/example.md new file mode 100644 index 0000000..457f4fd --- /dev/null +++ b/src/content/docs/v0.6/guides/example.md @@ -0,0 +1,12 @@ +--- +title: Example Guide +description: A guide in my new Starlight docs site. +slug: v0.6/guides/example +--- + +Guides lead a user through a specific task they want to accomplish, often with a sequence of steps. +Writing a good guide requires thinking about what your users are trying to do. + +## Further reading + +* Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework diff --git a/src/content/docs/v0.6/index.mdx b/src/content/docs/v0.6/index.mdx new file mode 100644 index 0000000..434ad47 --- /dev/null +++ b/src/content/docs/v0.6/index.mdx @@ -0,0 +1,71 @@ +--- +title: A unified platform for simplified compute, storage, and networking. +description: Get started building your docs site with Starlight. +template: splash +hero: + title: | + OtterScale: + + One Platform, infinite possibilities. + + tagline: A unified platform for simplified compute, storage, and networking. + image: + file: ../../../assets/v0.6/otter-2.png + actions: + - text: Get Started + link: /v0.6/introduction/ + icon: right-arrow + - text: View on Github + link: https://github.com/otterscale/otterscale + icon: external + variant: minimal +slug: v0.6 +--- + +import { Card, CardGrid } from '@astrojs/starlight/components'; +import { Icon } from '@astrojs/starlight/components'; + +## Key Features + + + + KVM/QEMU VMs with live migration and GPU management + + + + Native Kubernetes and Juju charm deployment + + + + Built-in Ceph clusters with automated backup + + + + Integrated Prometheus and Grafana stack + + + + RBAC with LDAP/AD integration and SSO + + + + Curated catalog of ready-to-deploy apps + + + + Multi-node deployment with automatic failover + + + +## Explore Application Store + +import IntegrationGrid from '@components/ApplicationsGrid.astro'; + +**Vast Application Ecosystem** — Deploy complex applications easily from our curated store. Tap into a vast ecosystem of integrations to power any stack, anywhere. [Explore the Application Store](/v0.6/service/applications/04-store/). + + diff --git a/src/content/docs/v0.6/introduction.mdx b/src/content/docs/v0.6/introduction.mdx new file mode 100644 index 0000000..6c306a1 --- /dev/null +++ b/src/content/docs/v0.6/introduction.mdx @@ -0,0 +1,84 @@ +--- +title: Introduction +description: Overview of OtterScale. +slug: v0.6/introduction +--- + +import { Card, CardGrid, LinkCard, Steps, Aside } from '@astrojs/starlight/components'; +import { Image } from 'astro:assets'; +import logo2 from '../../../assets/v0.6/otter-2.png'; + +
+
+ OtterScale is a{' '} + Hyper-Converged Infrastructure (HCI) + platform that unifies compute, storage, networking, and virtualization into a scalable solution. + Seamlessly manage VMs, containers, GPUs, and applications through a single control plane with + enterprise-grade performance. +
+ + OtterScale Logo +
+ +## System Architecture + +OtterScale is built on a layered architecture that provides complete control from the hardware up to the application layer. + +### Core Layers + + + 1. **Hardware Layer**: Manages physical resources including Compute nodes, Storage nodes, and GPU accelerators. + 2. **Provisioning Layer (MAAS)**: Handles bare metal provisioning, OS deployment, and network configuration. + 3. **Orchestration Layer (Juju & Kubernetes)**: Manages application lifecycles and container orchestration. + 4. **Storage Layer (Ceph)**: Provides scalable, distributed storage for the cluster. + + +### Node Provisioning & Management + +OtterScale automates the lifecycle of physical nodes. Through the integration with MAAS, it handles power management (IPMI/Redfish), PXE booting, and OS installation. + +### Storage Topology + +The platform utilizes Ceph to provide a robust, self-healing storage fabric. Storage nodes are dedicated to managing data replication and distribution, ensuring high availability and performance for data-intensive workloads like AI model training. + +## Key Features + + + + KVM/QEMU VMs with live migration and GPU management + + + + Native Kubernetes and Juju charm deployment + + + + Built-in Ceph clusters with automated backup + + + + Integrated Prometheus and Grafana stack + + + + RBAC with LDAP/AD integration and SSO + + + + Curated catalog of ready-to-deploy apps + + + + Multi-node deployment with automatic failover + + + +## Next Steps + + + + + + + + diff --git a/src/content/docs/v0.6/reference/example.md b/src/content/docs/v0.6/reference/example.md new file mode 100644 index 0000000..c44d6c8 --- /dev/null +++ b/src/content/docs/v0.6/reference/example.md @@ -0,0 +1,12 @@ +--- +title: Example Reference +description: A reference page in my new Starlight docs site. +slug: v0.6/reference/example +--- + +Reference pages are ideal for outlining how things work in terse and clear terms. +Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting. + +## Further reading + +* Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework diff --git a/src/content/docs/v0.6/service/applications/01-workloads.mdx b/src/content/docs/v0.6/service/applications/01-workloads.mdx new file mode 100644 index 0000000..9720744 --- /dev/null +++ b/src/content/docs/v0.6/service/applications/01-workloads.mdx @@ -0,0 +1,93 @@ +--- +title: Workloads +description: Manage Kubernetes applications and workloads. +slug: v0.6/serviceapplications/01-workloads +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +The Workloads page provides a unified view of the applications running in your OtterScale cluster. It aggregates information about Deployments, StatefulSets, and DaemonSets, allowing you to monitor their health and perform basic management tasks. + +## Introduction + +The Workloads page displays a list of all applications. The table includes the following information: + +| Column | Description | +| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Name** | The name of the application.
**Clickable**: Navigates to the **[Workload Details](#workload-details)** page, where you can view in-depth information about the application's resources and status. | +| **Type** | The Kubernetes workload type (e.g., `Deployment`, `StatefulSet`, `DaemonSet`). | +| **Namespace** | The Kubernetes namespace where the application is deployed. | +| **Health** | The health status of the application, shown as a ratio of healthy pods to total pods. | +| **Service** | The number of Kubernetes Services associated with the application. | +| **Pod** | The total number of Pods managed by the application. | +| **Replica** | The desired number of replicas (instances) for the application. | +| **Container** | The number of containers defined in the application's pod spec. | +| **Volume** | The number of Persistent Volume Claims (PVCs) attached to the application. | +| **NodePort** | Displays any exposed NodePorts.
**Clickable**: Click the external link icon next to the port number to open the service in a new tab, using the node's IP address and the assigned NodePort. | + +## Workload Details + +Clicking on a workload's name takes you to the details page, which provides a comprehensive view of the application: + +* **Header**: Displays the application name, namespace, type, and associated labels. +* **Statistics Cards**: + * **Containers**: Lists the containers within the pods and their images. + * **Persistent Volume Claims**: Shows the storage volumes attached to the workload. + * **Storage Classes**: Indicates the storage classes used by the volumes. + +### Pods Table + +The **Pods Table** lists all individual pods managed by this workload. + +| Column | Description | +| :----------------- | :--------------------------------------------------------------------------------------------------------------------- | +| **Name** | The unique name of the pod. | +| **Phase** | The current lifecycle phase of the pod (e.g., `Running`, `Pending`). | +| **Ready** | The number of ready containers relative to the total number of containers in the pod. | +| **Restarts** | The number of times the pod's containers have been restarted. | +| **Last Condition** | The most recent condition or error status. If an issue exists, it displays the reason and message (hover for details). | +| **Terminal** | **Clickable**: Opens a web-based terminal session connected to the pod in a new window. | +| **Actions** | Provides options to manage the individual pod. | + +### Services Table + +The **Services Table** lists the Kubernetes Services associated with the workload, providing network access details. + +| Column | Description | +| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------ | +| **Name** | The name of the Kubernetes Service. | +| **Type** | The type of service (e.g., `ClusterIP`, `NodePort`, `LoadBalancer`). | +| **Cluster IP** | The internal IP address assigned to the service within the cluster. | +| **Ports** | Lists the port configurations, including the protocol (e.g., TCP/UDP), the exposed port, the NodePort (if applicable), and the target port. | + +## Manage Workloads + +You can manage the lifecycle of your applications using the **Actions** menu. + +### Workload Actions + +The **Actions** menu (three dots icon) for each application provides the following options: + +#### Restart + +Triggers a rolling restart of the application. This is useful for reloading configurations or clearing transient issues. + + + 1. Select **Restart** from the actions menu. + 2. Confirm the action to initiate the restart process. + + +#### Scale + +Allows you to adjust the number of replicas for the application. + + + + + 1. Select **Scale** from the actions menu. + 2. Enter the desired number of replicas. + 3. Click **Confirm** to update the application scale. + diff --git a/src/content/docs/v0.6/service/applications/02-services.mdx b/src/content/docs/v0.6/service/applications/02-services.mdx new file mode 100644 index 0000000..dbdd8e2 --- /dev/null +++ b/src/content/docs/v0.6/service/applications/02-services.mdx @@ -0,0 +1,25 @@ +--- +title: Services +description: Monitor Kubernetes Services and network access. +slug: v0.6/serviceapplications/02-services +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +The Services page provides a list of Kubernetes Services within your OtterScale cluster. Services define a logical set of Pods and a policy by which to access them, enabling network connectivity for your applications. + +## Introduction + +The Services page displays a list of all services. The table includes the following information: + +| Column | Description | +| :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Name** | The name of the Kubernetes Service. | +| **Type** | The type of service (e.g., `ClusterIP`, `NodePort`, `LoadBalancer`), which determines how the service is exposed. | +| **Cluster IP** | The internal IP address assigned to the service, used for communication within the cluster. | +| **Ports** | The number of ports exposed by the service. Hovering over the count reveals a detailed table with the following fields: **Protocol**, **Port**, **NodePort**, **TargetPort**, and **Name**. | +| **Endpoints** | For services of type `NodePort`, this column displays the accessible endpoints. Hovering over the endpoint name reveals the full URL (e.g., `http://:`), and a copy button allows you to quickly copy it to the clipboard. | + +## Manage Services + +Currently, the Services page is read-only and provides monitoring capabilities. You can view the configuration and access points for your services, but creation and modification are typically handled through the application deployment process (e.g., via the **Workloads** page or Helm charts). diff --git a/src/content/docs/v0.6/service/applications/03-secrets.mdx b/src/content/docs/v0.6/service/applications/03-secrets.mdx new file mode 100644 index 0000000..f713e86 --- /dev/null +++ b/src/content/docs/v0.6/service/applications/03-secrets.mdx @@ -0,0 +1,37 @@ +--- +title: Secrets +description: Manage sensitive information such as passwords, OAuth tokens, and ssh keys. +slug: v0.6/serviceapplications/03-secrets +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +The Secrets page allows you to view and manage Kubernetes Secrets within your OtterScale cluster. Secrets are used to store and manage sensitive information, such as passwords, OAuth tokens, and SSH keys, keeping them separate from your application code. + +## Introduction + +The Secrets page displays a list of all secrets in the selected namespace. The table includes the following information: + +| Column | Description | +| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------- | +| **Name** | The name of the secret. **Clickable**: Clicking the name opens a dialog where you can view the decoded key-value pairs stored in the secret. | +| **Namespace** | The Kubernetes namespace where the secret is stored. | +| **Type** | The type of the secret (e.g., `Opaque`, `kubernetes.io/service-account-token`), which defines how the data is used. | +| **Immutable** | Indicates whether the secret's data can be changed. A checkmark means it is immutable (read-only), while a cross means it can be modified. | +| **Labels** | Key-value pairs attached to the secret for organization and selection. | +| **Created At** | The time elapsed since the secret was created. Hovering over the time displays the exact creation timestamp. | + +## View Secret Details + +To view the sensitive data stored within a secret: + + + 1. Click on the **Name** of the secret in the table. + 2. A dialog window will appear, listing all keys contained in the secret. + 3. The values are automatically decoded (from Base64) and displayed. + 4. Use the **Copy** button next to a value to copy it to your clipboard. + + +## Manage Secrets + +Currently, the Secrets page provides a secure way to view and audit existing secrets. Creation and management of secrets are typically handled through your deployment workflows, CLI tools, or external secret management systems. diff --git a/src/content/docs/v0.6/service/applications/04-store.mdx b/src/content/docs/v0.6/service/applications/04-store.mdx new file mode 100644 index 0000000..4d95b9a --- /dev/null +++ b/src/content/docs/v0.6/service/applications/04-store.mdx @@ -0,0 +1,120 @@ +--- +title: Store +description: Discover and deploy applications using Helm charts. +slug: v0.6/serviceapplications/04-store +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +The Store page serves as a marketplace for discovering and deploying applications to your OtterScale cluster. It leverages Helm charts to package and manage applications, providing a user-friendly interface to browse, install, and manage releases. + +## Introduction + +The Store page displays a catalog of available applications (Helm charts). You can browse the catalog using filters for name, keyword, maintainer, and deprecation status. + +Each application card displays: + +* **Icon**: The application's logo. +* **Name**: The name of the application. +* **Version**: The current version of the chart. +* **Description**: A brief description of the application. +* **Repository**: The source repository of the chart (e.g., `otterscale/`). Official OtterScale charts are marked with a "Official" badge. + +## Managing the Catalog + +The Store provides tools to keep your application catalog up-to-date and flexible. You can find the **Import** and **Sync** buttons at the top right of the page. + +### Synchronize with ArtifactHub + +To populate the store with popular community applications, use the **Sync** feature. + +* Clicking the **Sync** button initiates a synchronization process with [ArtifactHub](https://artifacthub.io/). +* The system automatically fetches the **top 60 most popular Helm charts** based on ArtifactHub rankings. +* This ensures your cluster has quick access to widely used tools (such as Argo CD, Prometheus, or Airflow) without manual configuration. + +### Import Custom Charts + +If you need to deploy a specific chart that is not included in the standard catalog or the ArtifactHub sync list, you can import it manually. + + + 1. Click the **Import** button. + 2. In the **Import Chart** dialog, paste the direct link to the chart's `.tgz` file. + * *Example:* `https://charts.bitnami.com/bitnami/nginx-15.0.0.tgz` + 3. Click **Confirm**. + + + + +## Application Details + +Clicking on an application card opens a details panel with two main tabs: + +### Information + +Provides comprehensive details about the chart: + +* **Description**: Full description of the application. +* **Keywords**: Tags associated with the chart. +* **Dependencies**: Lists other charts required by this application. +* **Home**: Link to the application's homepage. +* **Sources**: Links to the source code. +* **Maintainers**: List of the chart's maintainers. + +### Releases + +Lists the installed instances (releases) of this chart in your cluster. The table includes: + +* **Name**: The name of the release. +* **Namespace**: The namespace where it is deployed. +* **Chart**: The chart version and application version. +* **Revision**: The revision number of the release. +* **Actions**: Options to manage the release (Edit, Rollback, Delete). + +## Manage Applications + +You can install new applications or manage existing releases directly from the Store. + +### Install an Application + +To deploy a new application: + + + 1. Click on the application card to open the details panel. + + 2. Click the **Install** button. + + 3. **Configuration**: + + * **Name**: Enter a name for the release. + * **Namespace**: Specify the target namespace. + * **Version**: Select the chart version to install. + * **Dry Run**: Toggle to simulate the installation without making changes. + * **Configuration**: Customize the `values.yaml` configuration for the chart. You can modify the parameters to override the chart's defaults, such as replica counts, resource limits, or service settings. The editor supports YAML syntax highlighting and validation. + + ```yaml + # Example Configuration + replicaCount: 1 + image: + repository: nginx + tag: stable + service: + type: ClusterIP + port: 80 + resources: + limits: + cpu: 100m + memory: 128Mi + ``` + + 4. Click **Confirm** to start the installation. Once installed, the application will appear in the **Releases** tab. + + +### Manage Releases + +For existing releases listed in the **Releases** tab, you can perform the following actions: + +* **Edit**: Update the release configuration (e.g., change values or upgrade version). +* **Rollback**: Revert the release to a previous revision. +* **Delete**: Uninstall the release from the cluster. diff --git a/src/content/docs/v0.6/service/compute.mdx b/src/content/docs/v0.6/service/compute.mdx new file mode 100644 index 0000000..47be3fd --- /dev/null +++ b/src/content/docs/v0.6/service/compute.mdx @@ -0,0 +1,95 @@ +--- +title: Compute +description: Manage Virtual Machines. +slug: v0.6/service/compute +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +The Compute section allows you to create and manage Virtual Machines (VMs) within the OtterScale cluster. You can provision new instances, monitor their resource usage, and perform lifecycle management operations. + +## Introduction + +The Compute page displays a list of all Virtual Machines. The table includes the following information: + +| Column | Description | +| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Name** | The name of the Virtual Machine. | +| **Status** | The current state of the VM (e.g., Running, Stopped). | +| **Namespace** | The Kubernetes namespace where the VM resides. | +| **Machine** | The physical node (machine) hosting the VM instance.
**Expandable**: Click to view machine details.See [Machine Details](/v0.6/basic/machines/#machine-details). | +| **Instance Type** | The hardware profile (CPU/RAM) assigned to the VM. | +| **Disk** | The storage volumes attached to the VM.
**Expandable**: Click to view and manage individual disks. See [Disk Management](#disk-management). | +| **Ports** | The network ports exposed by the VM.
**Expandable**: Click to view and manage port configurations. See [Port Management](#port-management). | +| **Created** | The timestamp when the VM was created. | +| **Metrics** | Real-time resource usage for CPU, Memory, and Storage. | +| **VNC** | Provides a direct VNC console connection to the VM. | + +## Manage Virtual Machines + +You can create new Virtual Machines or manage existing ones using the **Actions** menu. + +### Create a New Virtual Machine + +To provision a new VM: + + + 1. Click the **Create** button (plus icon) at the top of the page. + + 2. A modal window titled "Create Virtual Machine" will appear. + + 3. **Basic Configuration**: + + * **Name**: Enter a unique name for the VM. + * **Namespace**: Specify the namespace (defaults to `default`). + * **Instance Type**: Select a hardware profile from the dropdown list (displays CPU cores and Memory size). + * **Data Volume**: Select the bootable Data Volume (PVC) to use for the OS disk. + + 4. **Advanced Configuration** (Optional): + + * Expand the "Advanced" section to configure a **Startup Script** (Cloud-Init user data) for bootstrapping the instance. + + 5. Click **Confirm** to launch the Virtual Machine. + + +### Virtual Machine Actions + +The **Actions** menu (three dots icon) for each VM provides the following options: + +#### Lifecycle Management + +* **Pause/Resume**: Temporarily pause the VM execution or resume it. +* **Start/Stop**: Power on or power off the VM. +* **Restart**: Reboot the VM. + +#### Data Management + +* **Snapshot**: Create a point-in-time snapshot of the VM's state and data. +* **Restore**: Revert the VM to a previous snapshot. + +#### Operations + +* **Clone**: Create a duplicate of the VM. +* **Migrate**: Move the VM to a different physical node in the cluster. +* **Delete**: Permanently remove the Virtual Machine and its associated resources. + + + +## Disk Management + +The **Disk** column allows you to expand the row to view and manage the storage volumes attached to the Virtual Machine. + +* **View Disks**: See a list of all attached disks, including their name, size, and type. +* **Attach Disk**: Add a new Data Volume (PVC) to the VM. +* **Detach Disk**: Remove an existing disk from the VM. + +## Port Management + +The **Ports** column allows you to expand the row to view and manage the network ports exposed by the Virtual Machine. + +* **View Ports**: See a list of configured ports, including the port number, protocol (TCP/UDP), and target port. +* **Add Port**: Expose a new port on the VM service. +* **Remove Port**: Close an existing port. diff --git a/src/content/docs/v0.6/service/models.mdx b/src/content/docs/v0.6/service/models.mdx new file mode 100644 index 0000000..62646fd --- /dev/null +++ b/src/content/docs/v0.6/service/models.mdx @@ -0,0 +1,83 @@ +--- +title: Models +description: Manage and monitor AI/ML models and artifacts. +slug: v0.6/service/models +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +The Models page provides a unified view of all AI/ML models deployed in your OtterScale cluster. It aggregates information about model deployments and their artifacts, allowing you to monitor status, manage resources, and perform lifecycle operations. + +## Introduction + +The Models page displays a list of all models. The table includes the following columns (as shown in the UI): + +| Column | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------- | +| **Name** | The name of the model. | +| **Model Name** | The unique identifier of the model (modelName/id). | +| **Namespace** | The Kubernetes namespace where the model is deployed. | +| **Status** | The current status of the model (e.g., Running, Pending). | +| **Description** | The description of the model. | +| **Prefill** | Prefill configuration: vGPU memory %, replica, tensor (if available). | +| **Decode** | Decode configuration: vGPU memory %, replica, tensor (if available). | +| **First Deployed** | Timestamp of first deployment. | +| **Last Deployed** | Timestamp of last deployment. | +| **GPU Relation** | GPU resource relation (shown only if status is 'deployed'). | +| **Test** | Test button for model API (only available when the model is in the "ready" state; opens a dialog to test the model). | +| **Actions** | Management actions (update, delete, etc.). | + +### Pods Table + +The **Pods Table** (in the details view) lists all pods managed by this model, if available.\ +Click the expand icon at the beginning of a row to view detailed pod information. + +| Column | Description | +| :---------------------- | :--------------------------------------------------------------------------------------- | +| **Pod** | The unique name of the pod. | +| **Phase** | The current lifecycle phase of the pod (e.g., Running, Pending). | +| **Ready** | Number of ready containers vs total containers. | +| **Restarts** | Number of times containers in the pod have restarted. | +| **Conditions** | The most recent condition or error status for the pod. | +| **Time to First Token** | The sum of time (in seconds) taken to generate the first token for requests to this pod. | +| **Request Latency** | The 95th percentile end-to-end request latency (in seconds) for this pod. | +| **Log** | **Clickable**: Opens the log view for the pod. | +| **Create Time** | The timestamp when the pod was created. | + +## Manage Models + +You can manage the lifecycle of your models using the **Actions** menu. + +### Model Actions + +The **Actions** menu (three dots icon) for each model provides: + +#### Create + +Create a new model. + + + 1. Select **Create** from the actions menu or click the **Create** button. + 2. You can search for models using the cloud icon next to the input box, or select a model from your [model artifacts](/v0.6/service/settings/05-model-artifact/) by clicking the archive icon. + 3. Fill in the model configuration (name, namespace, prefill/decode, description, etc.). + 4. Confirm to deploy the model. + + +#### Update + +Modify the configuration of an existing model (such as prefill/decode, description, etc.). + + + 1. Select **Update** from the actions menu. + 2. Edit the desired fields. + 3. Confirm to apply the changes. + + +#### Delete + +Delete a model. + + + 1. Select **Delete** from the actions menu. + 2. Confirm deletion. + diff --git a/src/content/docs/v0.6/service/repositories.mdx b/src/content/docs/v0.6/service/repositories.mdx new file mode 100644 index 0000000..2f95540 --- /dev/null +++ b/src/content/docs/v0.6/service/repositories.mdx @@ -0,0 +1,120 @@ +--- +title: Repositories +description: Manage container images and Helm charts in the registry. +slug: v0.6/service/repositories +--- + +import { Steps, Aside, Tabs, TabItem } from '@astrojs/starlight/components'; + +The Repositories page allows you to view and manage the container images and Helm charts stored in your private registry. + +## Introduction + +The Repositories table displays a list of all repositories. The table includes the following information: + +| Column | Description | +| :------------- | :----------------------------------------------------------------------------------------------------------------------------- | +| **Name** | The name of the repository. | +| **Latest Tag** | The most recent tag associated with the repository. | +| **Size** | The total size of the repository. | +| **Manifests** | The number of manifests (versions/tags) in the repository. Clicking the external link icon opens a detailed list of manifests. | + +## Upload Instructions + +You can upload Docker images and Helm charts to the repository via your local terminal. + + + + + + + + + 1. Tag the image: + + ```bash + docker tag : /: + ``` + + 2. Push the image: + + ```bash + docker push /: + ``` + + 3. After uploading, navigate to the [Applications Store](/v0.6/service/applications/04-store/) to update the Helm chart configuration to use your custom image: + + ```yaml + # Docker image + image: + # -- Docker image registry + repository: / + # -- Docker pull policy + pullPolicy: IfNotPresent + # -- Docker image tag, overrides the image tag whose default is the chart appVersion. + tag: + ``` + + + + + + 1. Download a chart package from [Artifact Hub](https://artifacthub.io/). + + 2. Upload the downloaded chart: + + ```bash + helm push oci:/// --plain-http + ``` + + 3. After uploading, navigate to the [Applications Store](/v0.6/service/applications/04-store/) to deploy the Helm chart. + + + + +## Manage Repositories + + + +### View Manifests + +To view the specific versions or tags within a repository: + + + 1. Locate the repository in the list. + 2. Click the external link icon in the **Manifests** column. + 3. A side panel will open displaying all manifests (tags) for that repository. + + +### View Manifest Details + +You can inspect the details of a specific image or chart version. + + + 1. Open the **Manifests** list for a repository. + 2. Click on any manifest item. + 3. A dialog will appear showing detailed information: + * **Charts**: Displays version, description, dependencies, maintainers, and source links. + * **Images**: Displays author, creation time, architecture, and container configuration (ports, entrypoint, commands, etc.). + + +### Delete Manifest + +You can delete specific versions (manifests) from a repository. + + + 1. Open the **Manifests** list for a repository. + 2. Locate the specific tag/version you want to remove. + 3. Click the **Delete** button (trash icon). + 4. Confirm the deletion to permanently remove the manifest. + diff --git a/src/content/docs/v0.6/service/settings/01-extensions.mdx b/src/content/docs/v0.6/service/settings/01-extensions.mdx new file mode 100644 index 0000000..8083acc --- /dev/null +++ b/src/content/docs/v0.6/service/settings/01-extensions.mdx @@ -0,0 +1,63 @@ +--- +title: Extensions +description: Manage system extensions and add-ons. +slug: v0.6/servicesettings/01-extensions +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +The Extensions page allows you to manage the add-ons and system components that extend the functionality of your OtterScale cluster. Extensions are grouped into bundles based on their purpose, such as General, Model, Registry, Virtual Machine, and Storage. + +## Introduction + +Extensions are essential components that enable specific features within the platform. The Extensions page organizes these components into expandable bundles. Each bundle displays a progress bar indicating the installation status of the extensions within it. + +### Extension Bundles + +The available extension bundles include: + +| Bundle | Description | +| :--------------------- | :----------------------------------------------------------------------- | +| **General** | Core system extensions required for basic platform functionality. | +| **Container Registry** | Extensions for managing container images and registries. | +| **Model** | Extensions related to Large Language Model (LLM) serving and management. | +| **Virtual Machine** | Extensions enabling Virtual Machine (VM) virtualization and management. | +| **Storage** | Extensions for persistent storage management and volume provisioning. | + +## Manage Extensions + +You can install or upgrade extensions directly from the bundle card. + +### Install Extensions + +If a bundle has missing extensions (indicated by a progress bar that is not full and a red or yellow color), you can install them: + + + 1. Locate the bundle you want to install (e.g., "Model"). + 2. Click the **Install** button on the right side of the bundle card. + 3. The system will begin installing the missing extensions. A toast notification will appear to track the progress. + 4. Once completed, the progress bar will turn green, indicating all extensions are installed. + + +### Upgrade Extensions + +If all extensions in a bundle are installed but updates are available, you can upgrade them: + + + 1. Locate the bundle with available updates. + 2. Click the **Upgrade** button on the right side of the bundle card. + 3. The system will update the extensions to their latest versions. + + +### View Extension Details + +You can expand any bundle to view the individual extensions contained within it. + +1. Click on the bundle card to expand the accordion. +2. You will see a list of individual extensions. +3. Each extension card displays: + * **Icon**: Visual identifier for the extension. + * **Name**: The display name of the extension. + * **Version**: The currently installed version (or the latest available version). + * **Status**: A green checkmark indicates the extension is installed and active; a red minus circle indicates it is not installed. + * **Description**: A brief explanation of what the extension does. diff --git a/src/content/docs/v0.6/service/settings/02-built-in-test.mdx b/src/content/docs/v0.6/service/settings/02-built-in-test.mdx new file mode 100644 index 0000000..0378df1 --- /dev/null +++ b/src/content/docs/v0.6/service/settings/02-built-in-test.mdx @@ -0,0 +1,72 @@ +--- +title: Built-in Test +description: Run performance benchmarks for storage subsystems. +slug: v0.6/servicesettings/02-built-in-test +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +The Built-in Test page allows you to run performance benchmarks on your storage infrastructure. It provides tools to validate the performance of block storage (using FIO) and object storage (using Warp). + +## Introduction + +The page is divided into two main sections: + +* **IO Test**: Benchmarks disk I/O performance using the Flexible I/O tester (FIO). This is useful for testing Ceph block devices or NFS shares. +* **Object Storage Test**: Benchmarks S3-compatible object storage performance using MinIO Warp. This supports testing internal (Ceph, MinIO) and external S3 endpoints. + +## IO Test (FIO) + +FIO (Flexible I/O tester) is a standard tool for benchmarking disk I/O. You can use it to simulate specific workload patterns and measure the performance of your storage backend. + +### Run an IO Test + +To start a new IO benchmark: + + + 1. Navigate to the **IO Test** tab. + 2. Click the **Create** button. + 3. Configure the test parameters: + * **Target**: Select the storage target (e.g., Ceph Block Pool or NFS). + * **Access Mode**: Choose the I/O pattern (Read, Write, Random Read, Random Write, etc.). + * **Block Size**: Set the size of I/O units (e.g., 4k, 64k). + * **IO Depth**: Define the queue depth for asynchronous I/O. + * **Run Time**: Set the duration of the test. + 4. Click **Confirm** to start the test. + + +### Understanding Results + +Once the test completes, the results table displays key metrics: + +* **IOPS**: Input/Output Operations Per Second. Higher is better for transactional workloads. +* **Bandwidth**: Data transfer rate (MB/s). Higher is better for streaming workloads. +* **Latency**: The time taken to complete an I/O request (Min, Max, Mean). Lower is better. + +## Object Storage Test (Warp) + +Warp is a high-performance S3 benchmarking tool. It is designed to measure the throughput and latency of object storage services. + +### Run an Object Storage Test + +To start a new Object Storage benchmark: + + + 1. Navigate to the **Object Storage Test** tab. + 2. Click the **Create** button. + 3. Configure the test parameters: + * **Target**: Select an internal service (Ceph, MinIO) or configure an external S3 endpoint (Host, Access Key, Secret Key). + * **Operation**: Choose the operation to test (PUT, GET, DELETE, etc.). + * **Object Size**: Set the size of the objects used in the test. + * **Duration**: Set the duration of the benchmark. + * **Concurrency**: (Optional) Adjust the number of concurrent operations. + 4. Click **Confirm** to start the test. + + +### Understanding Results + +The results table provides insights into the object storage performance: + +* **Throughput**: The speed of data transfer (Fastest, Median, Slowest). +* **Operations**: The rate of object operations (OPS). +* **Total Transferred**: The total amount of data and number of objects processed during the test. diff --git a/src/content/docs/v0.6/service/settings/03-data-volume.mdx b/src/content/docs/v0.6/service/settings/03-data-volume.mdx new file mode 100644 index 0000000..3746b1b --- /dev/null +++ b/src/content/docs/v0.6/service/settings/03-data-volume.mdx @@ -0,0 +1,68 @@ +--- +title: Data Volume +description: Manage persistent storage volumes for Virtual Machines. +slug: v0.6/servicesettings/03-data-volume +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +The Data Volume page allows you to manage persistent storage volumes (DataVolumes) used by Virtual Machines in the OtterScale cluster. DataVolumes provide a way to automate the importing, cloning, and uploading of data into Persistent Volume Claims (PVCs). + +## Introduction + +The Data Volume page displays a list of configured DataVolumes. The table includes the following information: + +| Column | Description | +| :------------ | :---------------------------------------------------------------------------------------------------------------------- | +| **Name** | The name of the DataVolume. | +| **Namespace** | The Kubernetes namespace where the DataVolume resides. | +| **Phase** | The current status of the DataVolume (e.g., Succeeded, ImportInProgress). | +| **Source** | The source of the data (e.g., HTTP URL, Blank Image, PVC). Hovering over the badge reveals detailed source information. | +| **Progress** | The progress of the data import or clone operation. | +| **Size** | The capacity of the volume. | + +## Manage Data Volumes + +You can create new DataVolumes or manage existing ones using the **Actions** menu. + +### Create a New Data Volume + +To create a new DataVolume: + + + 1. Click the **Create** button (plus icon) at the top of the page. + + 2. A modal window titled "Create Data Volume" will appear. + + 3. **Configuration**: + + * **Name**: Enter a unique name for the DataVolume. + * **Namespace**: Specify the namespace (defaults to `default`). + * **Size**: Set the capacity of the volume (e.g., 10 GB). + * **Source**: Enter the URL of the source image (e.g., a cloud image URL). You can use the "Cloud Image" button to find common Ubuntu cloud images. + + 4. Click **Confirm** to create the DataVolume. + + +### Data Volume Actions + +The **Actions** menu (three dots icon) for each DataVolume provides the following options: + +#### Extend + +Allows you to increase the size of an existing DataVolume. + + + 1. Select **Extend** from the actions menu. + 2. Enter the new, larger size for the volume. + 3. Click **Confirm** to apply the changes. + + +#### Delete + +Permanently removes the DataVolume and its associated data. + + diff --git a/src/content/docs/v0.6/service/settings/04-instance-type.mdx b/src/content/docs/v0.6/service/settings/04-instance-type.mdx new file mode 100644 index 0000000..b16d684 --- /dev/null +++ b/src/content/docs/v0.6/service/settings/04-instance-type.mdx @@ -0,0 +1,57 @@ +--- +title: Instance Type +description: Manage hardware profiles for Virtual Machines. +slug: v0.6/servicesettings/04-instance-type +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +The Instance Type page allows you to define and manage hardware profiles (InstanceTypes) for Virtual Machines. An InstanceType specifies the CPU and Memory resources allocated to a VM. + +## Introduction + +The Instance Type page displays a list of available hardware profiles. The table includes the following information: + +| Column | Description | +| :-------------- | :---------------------------------------------------------------- | +| **Name** | The name of the Instance Type (e.g., `small`, `medium`, `large`). | +| **Namespace** | The Kubernetes namespace where the Instance Type is defined. | +| **CPU Cores** | The number of virtual CPU cores allocated. | +| **Memory** | The amount of RAM allocated. | +| **Create Time** | The timestamp when the Instance Type was created. | + +## Manage Instance Types + +You can create new Instance Types or manage existing ones using the **Actions** menu. + +### Create a New Instance Type + +To define a new hardware profile: + + + 1. Click the **Create** button (plus icon) at the top of the page. + + 2. A modal window titled "Create Instance Type" will appear. + + 3. **Configuration**: + + * **Name**: Enter a unique name for the Instance Type. + * **Namespace**: Specify the namespace (defaults to `default`). + * **CPU Cores**: Enter the number of CPU cores. + * **Memory**: Set the amount of memory (e.g., 4 GB). + + 4. Click **Confirm** to create the Instance Type. + + +### Instance Type Actions + +The **Actions** menu (three dots icon) for each Instance Type provides the following options: + +#### Delete + +Permanently removes the Instance Type. + + diff --git a/src/content/docs/v0.6/service/settings/05-model-artifact.mdx b/src/content/docs/v0.6/service/settings/05-model-artifact.mdx new file mode 100644 index 0000000..3df3d1b --- /dev/null +++ b/src/content/docs/v0.6/service/settings/05-model-artifact.mdx @@ -0,0 +1,56 @@ +--- +title: Model Artifact +description: Manage model files and weights for AI/ML models. +slug: v0.6/servicesettings/05-model-artifact +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +The Model Artifact page allows you to manage model artifacts for your AI/ML models. You can upload, view, and delete model artifacts associated with different models and namespaces. + +## Introduction + +The Model Artifact page displays a list of all model artifacts. The table includes the following columns: + +| Column | Description | +| :-------------- | :----------------------------------------------------------------- | +| **Name** | The name of the model artifact. | +| **Namespace** | The Kubernetes namespace where the artifact is stored. | +| **Model Name** | The name of the associated model. | +| **Status** | The current job status for downloading or processing the artifact. | +| **Phase** | The current phase/status of the artifact. | +| **Size** | The size of the artifact (GB/TB). | +| **Volume** | The volume name where the artifact is stored. | +| **Create Time** | The timestamp when the artifact was created. | +| **Actions** | Management actions (delete). | + +## Manage Model Artifacts + +You can create new model artifacts or manage existing ones using the **Actions** menu. + +### Create a New Model Artifact + +To upload a new model artifact: + + + 1. Click the **Create** button (plus icon) at the top of the page. + 2. A modal window titled "Create Model Artifact" will appear. + 3. **Configuration**: + * **Name**: Enter a unique name for the artifact. + * **Namespace**: Select the namespace (usually `llm-d`). + * **Model Name**: Select the model name (supports Hugging Face models). + * **Size**: Set the artifact size (GB/TB). + 4. Click **Confirm** to create the model artifact. + + +### Model Artifact Actions + +The **Actions** menu (trash icon) for each model artifact provides the following option: + +#### Delete + +Permanently removes the model artifact. + + diff --git a/src/content/docs/v0.6/service/storage/01-osd.mdx b/src/content/docs/v0.6/service/storage/01-osd.mdx new file mode 100644 index 0000000..5e7bf6c --- /dev/null +++ b/src/content/docs/v0.6/service/storage/01-osd.mdx @@ -0,0 +1,56 @@ +--- +title: OSD +description: Monitor and manage Object Storage Daemons (OSDs). +slug: v0.6/servicestorage/01-osd +--- + +import { Steps, Aside, Card, CardGrid } from '@astrojs/starlight/components'; + +The OSD (Object Storage Daemon) page provides a detailed overview of the storage daemons in your Ceph cluster.\ +Each OSD represents a logical disk that maps to an underlying physical device such as NVMe, SSD, or HDD. + +### Statistics Overview + +At the top of the page, you will find a dashboard summarizing the state of OSD capacity and availability across the cluster: + + + + The total number of OSDs detected by the cluster. + + + + The percentage of overall raw storage usage across all OSDs. + + + +## Introduction + +The OSD page lists all Object Storage Daemons currently available in the cluster. +Each row represents one OSD instance and includes the following information: + +| Column | Description | +| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Name** | The unique identifier of the OSD (e.g., `osd.0`). | +| **State** | Indicates the operational status. **Up** means the daemon is running. **In** means the OSD is included in the CRUSH map and is storing data. | +| **Exists** | Shows whether the OSD physically exists and is recognized by the cluster. | +| **Device Class** | The storage device type assigned to the OSD, such as `hdd`, `ssd`, or `nvme`. This information helps determine data placement and CRUSH behavior. | +| **Machine** | The hostname of the node hosting the OSD. Selecting the hostname opens the machine detail page. | +| **Placement Group** | The number of Placement Groups (PGs) currently assigned to the OSD. | +| **Usage** | A visual indicator showing the used and total storage capacity of the OSD (Used Space / Total Space). | +| **IOPS** | A real-time chart showing input and output operations per second (Input vs. Output). | +| **Throughput** | A real-time chart showing read and write data throughput (Read vs. Write). | + +## Manage OSDs + +Each OSD provides an Actions menu for administrative operations. + +#### View SMART + +Retrieves S.M.A.R.T. (Self-Monitoring, Analysis and Reporting Technology) information from the physical disk associated with the OSD.\ +This data helps assess hardware health and identify potential failures. + + + 1. Open the Actions menu for the selected OSD. + 2. Click **Do S.M.A.R.T.** + 3. A dialog will appear showing the full S.M.A.R.T. report for the device. + diff --git a/src/content/docs/v0.6/service/storage/02-pool.mdx b/src/content/docs/v0.6/service/storage/02-pool.mdx new file mode 100644 index 0000000..25b1c08 --- /dev/null +++ b/src/content/docs/v0.6/service/storage/02-pool.mdx @@ -0,0 +1,80 @@ +--- +title: Pool +description: Manage Ceph storage pools. +slug: v0.6/servicestorage/02-pool +--- + +import { Steps, Aside, Card, CardGrid } from '@astrojs/starlight/components'; + +The Pool page allows you to manage Ceph storage pools, which are logical partitions for storing objects. Pools provide a layer of abstraction between clients and the underlying OSDs, allowing you to configure data durability, availability, and performance policies. + +### Statistics Overview + +At the top of the page, you will find a dashboard summarizing the state of pool configuration within the cluster: + + + + The total number of storage pools currently defined in the system. + + + +## Introduction + +The Pool page displays a list of all storage pools. The table includes the following information: + +| Column | Description | +| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Name** | The name of the pool. A spinner icon indicates if the pool is currently updating. | +| **Type** | The type of the pool, either `Replicated` (copies data) or `Erasure` (uses erasure coding for efficiency). It also displays configuration details like replica count or erasure coding profile (k+m). | +| **Applications** | The applications enabled for this pool (e.g., `rbd`, `cephfs`, `rgw`). | +| **PG State** | The state of the Placement Groups (PGs) within the pool (e.g., `active`, `clean`, `degraded`). | +| **Usage** | A progress bar indicating the amount of data stored in the pool relative to its total logical capacity. | + +## Create Pool + +You can create new storage pools to meet specific application requirements. +The create dialog includes configuration fields for pool type, replica size or erasure coding settings, application assignment, and optional quotas. + + + 1. Click the **Create** button. + 2. **Name**: Enter a unique name for the pool. + 3. **Type**: Select the pool type: + * **Replicated**: Stores multiple copies of data. Ideal for high performance and fast recovery. + * **Replicated Size**: Specify the number of replicas (e.g., 3). + * **Erasure**: Uses erasure coding to save space. Ideal for cold storage or large datasets. + * **EC Overwrite**: Enable if you need to support overwrites (required for RBD/CephFS on EC pools). + 4. **Quota**: Optionally set limits on the pool's usage: + * **Max Bytes**: The maximum amount of data (in GB or TB) the pool can store. + 5. **Advanced Settings (Optional)**: + * **Max Objects**: The maximum number of objects the pool can store. + 6. Click **Confirm** to create the pool. + + +## Manage Pools + +You can modify or delete existing pools using the **Actions** menu. + +### Edit Pool + +Allows you to modify the pool's configuration, such as quotas. + + + 1. Select **Edit** from the actions menu (pencil icon). + 2. Update the **Quota Size**, or **Quota Objects** as needed. + 3. Click **Confirm** to save changes. + + +### Delete Pool + +Permanently removes a storage pool and all its data. + + + 1. Select **Delete** from the actions menu (trash icon). + 2. Type the name of the pool to confirm deletion. + 3. Click **Confirm** to permanently delete the pool. + + + diff --git a/src/content/docs/v0.6/service/storage/03-block-device.mdx b/src/content/docs/v0.6/service/storage/03-block-device.mdx new file mode 100644 index 0000000..aebe8d7 --- /dev/null +++ b/src/content/docs/v0.6/service/storage/03-block-device.mdx @@ -0,0 +1,105 @@ +--- +title: Block Device +description: Manage Ceph RADOS Block Devices (RBD). +slug: v0.6/servicestorage/03-block-device +--- + +import { Steps, Aside, Card, CardGrid } from '@astrojs/starlight/components'; + +The Block Device page allows you to manage Ceph RADOS Block Devices (RBD). RBDs are block-based storage devices that are striped across the cluster, providing high-performance and reliable storage for virtual machines, containers, and other applications. + +### Statistics Overview + +At the top of the page, you will find a dashboard summarizing the state of RBD images stored in the cluster: + + + + The total number of RADOS Block Device (RBD) images currently stored across all pools. + + + + Displays the aggregated storage usage of all block device images, including total used capacity and total provisioned quota. + + + +## Introduction + +The Block Device page displays a list of all RBD images. The table includes the following information: + +| Column | Description | +| :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------- | +| **Name** | The name of the block device image. | +| **Pool Name** | The storage pool where the image is stored. | +| **Usage** | A progress bar showing the storage capacity usage (Used Space / Quota Size). | +| **Snapshots** | The number of snapshots taken of this block device. Clicking the external link icon opens a detailed view of the [snapshots](#manage-snapshots). | + +## Create Block Device + +You can create new block devices to provide storage for your applications. + + + 1. Click the **Create** button. + 2. **Image Name**: Enter a unique name for the block device. + 3. **Pool Name**: Select the storage pool to host the image. + 4. **Quota Size**: Specify the size of the block device (e.g., 100 GB). + 5. **Advanced Settings** (Optional): + * **Striping**: Configure **Object Size**, **Stripe Unit**, and **Stripe Count** to optimize performance for specific workloads. + * **Features**: Enable or disable RBD features like **Layering**, **Exclusive Lock**, **Object Map**, **Fast Diff**, and **Deep Flatten**. + 6. Click **Confirm** to create the block device. + + +## Manage Block Devices + +You can modify or delete existing block devices using the **Actions** menu. + +### Edit Block Device + +Allows you to expand or shrink the block device. + + + + + 1. Select **Edit** from the actions menu (pencil icon). + 2. Update the **Quota Size** to increase the device size. + 3. Click **Confirm** to save changes. + + +### Delete Block Device + +Permanently removes a block device and all its data. + + + 1. Select **Delete** from the actions menu (trash icon). + 2. Type the name of the image to confirm deletion. + 3. Click **Confirm** to permanently delete the block device. + + + + +## Manage Snapshots + +Snapshots provide a read-only copy of the block device state at a specific point in time. You can view and manage snapshots by clicking the external link icon in the **Snapshots** column. + +### Snapshot List + +The snapshot list displays the following information: + +| Column | Description | +| :---------- | :------------------------------------------------------------------------------ | +| **Name** | The name of the snapshot. | +| **Protect** | Indicates whether the snapshot is protected from deletion. | +| **Usage** | A progress bar showing the storage usage of the snapshot. | + +### Snapshot Actions + +The **Actions** menu for each snapshot provides the following options: + +* **Rollback**: Reverts the block device to the state captured in the snapshot. **Note**: This will discard any changes made since the snapshot was taken. +* **Protect**: Prevents the snapshot from being deleted. Useful for critical backups. +* **Unprotect**: Removes the protection, allowing the snapshot to be deleted. +* **Delete**: Permanently removes the snapshot. diff --git a/src/content/docs/v0.6/service/storage/04-file-system.mdx b/src/content/docs/v0.6/service/storage/04-file-system.mdx new file mode 100644 index 0000000..e0d16ba --- /dev/null +++ b/src/content/docs/v0.6/service/storage/04-file-system.mdx @@ -0,0 +1,220 @@ +--- +title: File System +description: Manage Ceph File Systems (CephFS) and NFS exports. +slug: v0.6/servicestorage/04-file-system +--- + +import { Steps, Aside, Card, CardGrid } from '@astrojs/starlight/components'; + +The File System page allows you to manage Ceph File Systems (CephFS) and Network File System (NFS) exports. CephFS provides a POSIX-compliant file system on top of the Ceph cluster, while NFS exports allow you to share these file systems with standard NFS clients. + +The page is divided into two main sections: **NFS** and **Group**. + +## NFS + +The NFS section allows you to manage subvolumes and export them via NFS. + +### Statistics Overview + +At the top of the page, you will find a dashboard summarizing the state of NFS exports configured in the system: + + + + The total number of NFS exports created from CephFS subvolumes. + + + +### Introduction + +The NFS table displays a list of subvolumes. The table includes the following information: + +| Column | Description | +| :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Name** | The name of the subvolume. | +| **Pool Name** | The data pool where the subvolume is stored. | +| **Export** | Displays the NFS export host. Click the information icon in the Export column to view the export IP, path, allowed clients, and the mount command. Use the copy icon to copy the mount command directly. | +| **Usage** | A progress bar showing the storage capacity usage (Used Space / Quota Size). | +| **Created Time** | Displays how long ago the NFS export was created, relative to the current time. | +| **Snapshots** | The number of snapshots taken of this subvolume. Clicking the external link icon opens a detailed view of the [snapshots](#snapshot-list). | + +### Create NFS Export + +You can create new subvolumes and export them via NFS. + + + 1. Click the **Create** button. + 2. **Name**: Enter a unique name for the subvolume. + 3. **Group**: Displays the current subvolume group (default is `default`). + 4. **Quota Size**: Specify the size limit for the subvolume (e.g., 10 GB). + 5. Click **Confirm** to create the subvolume. + + +### Mount NFS Export + +After an NFS export is created and access is granted, clients can mount the export using standard NFS commands. + +#### Prerequisites + +* An NFS export has been created. +* The client IP address (or CIDR range) has been granted access to the export. +* The client has NFS utilities installed. + + + 1. Open the information icon in the Export column of the NFS table. + 2. Copy the mount command using the copy icon. + 3. Log in to the target client machine. + 4. Create a mount directory if it does not already exist: + ```bash + sudo mkdir -p /mnt/nfs + ``` + 5. Run the copied mount command: + ```bash + sudo mount -t nfs4 -o nfsvers=4.1 -v : /mnt/nfs + ``` + 6. Verify that the file system is mounted successfully: + ```bash + mount | grep nfs + ``` + + +### Manage NFS Exports + +You can manage access, modify quotas, or delete NFS exports using the **Actions** menu. + +#### Grant/Revoke Access + +Control which clients can access the NFS export. + +* **Grant Access**: Adds a client IP address to the allowed list. For example, You can specify a single IP address 192.168.10.151 or a CIDR range 192.168.10.0/24. +* **Revoke Access**: Removes a client IP address from the allowed list. + +#### Edit NFS Export + +Allows you to resize the subvolume quota. + + + 1. Select **Edit** from the actions menu (pencil icon). + 2. Update the **Quota Size**. + 3. Click **Confirm** to save changes. + + +#### Delete NFS Export + +Permanently removes the subvolume and its export. + + + 1. Select **Delete** from the actions menu (trash icon). + 2. Type the name of the subvolume to confirm deletion. + 3. Click **Confirm** to permanently delete the subvolume. + + + + +### Manage Snapshots + +Snapshots provide a read-only copy of the subvolume at a specific point in time. You can view and manage snapshots by clicking the external link icon in the **Snapshots** column. + +#### Snapshot List + +The snapshot list displays the following information: + +| Column | Description | +| :----------------- | :---------------------------------------------------------------------------- | +| **Name** | The name of the snapshot. | +| **Pending Clones** | Indicates if there are any pending clones based on this snapshot. | +| **Created Time** | Displays how long ago the snapshot was created, relative to the current time. | + +#### Snapshot Actions + +#### Create Snapshot + +Create Snapshot allows you to capture a read-only point-in-time copy of the subvolume. + + + 1. Click the external link icon in the Snapshots column to open the snapshot list. + 2. Click the Create button. + 3. Name: Enter a unique name for the snapshot. + 4. Click Confirm to create the snapshot. + + +#### Delete Snapshot + +Delete Snapshot permanently removes an existing snapshot. + + + 1. Click the external link icon in the Snapshots column to open the snapshot list. + 2. Open the Actions menu for the target snapshot. + 3. Select Delete. + 4. Type the name of the snapshot to confirm deletion. + 5. Click Confirm to permanently delete the snapshot. + + + + +## Group + +The Group section allows you to manage subvolume groups, which are used to organize subvolumes. + +### Statistics Overview + +At the top of the page, you will find a dashboard summarizing the state of subvolume groups configured in the file system: + + + + The total number of subvolume groups defined in the file system. + + + +### Introduction + +The Group table displays a list of subvolume groups. The table includes the following information: + +| Column | Description | +| :--------------- | :----------------------------------------------------------------------------------- | +| **Name** | The name of the subvolume group. | +| **Pool Name** | The data pool associated with the group. | +| **Usage** | A progress bar showing the cumulative usage of all subvolumes in the group. | +| **Created Time** | Displays how long ago the subvolume group was created, relative to the current time. | + +### Create Group + +You can create new subvolume groups to organize your file systems. + + + 1. Click the **Create** button. + 2. **Name**: Enter a unique name for the group. + 3. **Quota Size**: Optionally set a quota for the group. + 4. Click **Confirm** to create the group. + + +### Manage Groups + +#### Edit Group + +Allows you to resize the group quota. + + + 1. Select **Edit** from the actions menu (pencil icon). + 2. Update the **Quota Size**. + 3. Click **Confirm** to save changes. + + +#### Delete Group + +Permanently removes a subvolume group. + + + + + 1. Select **Delete** from the actions menu (trash icon). + 2. Type the name of the group to confirm deletion. + 3. Click **Confirm** to permanently delete the group. + + + diff --git a/src/content/docs/v0.6/service/storage/05-smb.mdx b/src/content/docs/v0.6/service/storage/05-smb.mdx new file mode 100644 index 0000000..697fa1a --- /dev/null +++ b/src/content/docs/v0.6/service/storage/05-smb.mdx @@ -0,0 +1,74 @@ +--- +title: SMB +description: Manage Samba (SMB) shares. +slug: v0.6/servicestorage/05-smb +--- + +import { Steps, Card, CardGrid } from '@astrojs/starlight/components'; + +The SMB page allows you to manage Samba (SMB) shares, enabling file sharing across your network with Windows and other SMB-compatible clients. You can configure security modes, user access, and share properties. + +### Statistics Overview + +At the top of the page, you will find a dashboard summarizing the state of SMB shares configured in the system: + + + + The total number of SMB shares currently defined in the system. + + + +## Introduction + +The SMB table displays a list of all SMB shares. The table includes the following information: + +| Column | Description | +| :--------------- | :------------------------------------------------------------------------------------------------------------- | +| **URI** | The connection URI for the share (e.g., `smb:///`). | +| **Health** | The health status of the share. | +| **Size** | The allocated storage size for the share. | +| **Browsable** | Indicates if the share is visible in network browsing lists. | +| **Read Only** | Indicates if the share is read-only. | +| **Guest OK** | Indicates if guest access (no password) is allowed. | +| **Map To Guest** | Specifies how login requests with invalid credentials are handled (e.g., `Never`, `Bad User`, `Bad Password`). | +| **Mode** | The security mode of the share (`User` or `Active Directory`). | +| **Valid Users** | A list of users or groups allowed to access the share. | + +## Create SMB Share + +You can create new SMB shares to expose storage to your network. + + + 1. Click the **Create** button. + 2. **Name**: Enter a unique name for the share. + 3. **Port**: Optionally specify a custom port (use 445 port for Windows client). + 4. **Size**: Specify the storage size for the share (e.g., 100 GB). + 5. **Common Configuration**: + * **Map To Guest**: Configure how to handle guest access. + 6. **Security Configuration**: + * **Mode**: Select **User** (local users) or **Active Directory**. + * **Local Users** (User Mode): Manage local username and password credentials. + * **Realm** (AD Mode): Enter the Active Directory realm. + * **Join Source** (AD Mode): Provide credentials to join the domain. + * **Valid Users**: Specify which users or groups are allowed to access the share. + 7. **Share Settings**: + * **Browsable**: Toggle to make the share visible. + * **Read Only**: Toggle to prevent write access. + * **Guest Accessible**: Toggle to allow access without authentication. + 8. Click **Confirm** to create the SMB share. + + +## Manage SMB Shares + +You can modify existing SMB shares using the **Actions** menu. + +### Edit SMB Share + +Allows you to update the share's configuration, including size, security settings, and access controls. + + + 1. Select **Update** from the actions menu (pencil icon). + 2. Update the desired settings. + 3. Click **Confirm** to save changes. + 4. Wait a few minutes for the settings to take effect. + diff --git a/src/content/docs/v0.6/service/storage/06-object.mdx b/src/content/docs/v0.6/service/storage/06-object.mdx new file mode 100644 index 0000000..221edd6 --- /dev/null +++ b/src/content/docs/v0.6/service/storage/06-object.mdx @@ -0,0 +1,205 @@ +--- +title: Object +description: Manage Ceph Object Gateway (RGW) buckets and users. +slug: v0.6/servicestorage/06-object +--- + +import { Steps, Aside, Card, CardGrid } from '@astrojs/starlight/components'; + +The Object page allows you to manage the Ceph Object Gateway (RGW), which provides an S3-compatible object storage interface. You can manage buckets for storing objects and users for controlling access. + +The page is divided into two main sections: **Bucket** and **User**. + +## Bucket + +The Bucket section allows you to manage S3 buckets. + +### Statistics Overview + +At the top of the page, you will find a dashboard summarizing the state of S3 storage: + + + + The total number of S3 buckets currently defined in the system. + + The RGW endpoint IP that clients use to access the bucket via S3-compatible APIs. + + + + The combined storage consumption across all buckets, including object data and metadata overhead. + + + +### Introduction + +The Bucket table displays a list of all buckets. The table includes the following information: + +| Column | Description | +| :--------------- | :-------------------------------------------------------------------------- | +| **Name** | The name of the bucket. | +| **Owner** | The user ID of the bucket owner. | +| **Usage** | The total size of objects stored in the bucket. | +| **Created Time** | Displays how long ago the bucket was created, relative to the current time. | + +### Create Bucket + +You can create new buckets to store your data. + + + 1. Click the **Create** button. + 2. **Name**: Enter a unique name for the bucket. + 3. **Owner**: Select the owner of the bucket from the list of users. + 4. **Policy** (Optional): Enter a JSON policy to define access permissions. You can use the provided links to generate or reference AWS policies. + 5. **Access Control List** (Optional): Select a canned ACL (e.g., `private`, `public-read`) to define basic access permissions. + 6. Click **Confirm** to create the bucket. + + +### Access Bucket with S3 Browser + +This section demonstrates how to access a Ceph Object Gateway (RGW) bucket using S3 Browser, a graphical S3 client. +This approach is useful for manual verification, browsing objects, and basic upload/download operations without writing code. + +#### Prerequisites + +* S3 Browser installed on the client machine (Windows). + + + 1. Create a user in User section. + 2. Create an access key for the user and copy the secret key. + 3. Create a bucket and assign the user as the owner. The bucket owner always has full control of the bucket regardless of the selected ACL. + 4. Open S3 Browser. + 5. Fill in the account settings: + * Account type: S3 compatible storage + * API endpoint: RGW endpoint + * Access Key ID: User’s access key. + * Secret Access Key: The copied secret key. + * Use secure transfer: Disable SSL + 6. Add new account + + +### Manage Buckets + +You can modify or delete existing buckets using the **Actions** menu. + +#### Edit Bucket + +Allows you to update the bucket's owner, policy, or ACL. + + + 1. Select **Edit** from the actions menu (pencil icon). + 2. Update the **Owner**, **Policy**, or **Access Control List** as needed. + 3. Click **Confirm** to save changes. + + +#### Delete Bucket + +Permanently removes a bucket and all its objects. + + + 1. Select **Delete** from the actions menu (trash icon). + 2. Type the name of the bucket to confirm deletion. + 3. Click **Confirm** to permanently delete the bucket. + + + + +## User + +The User section allows you to manage RGW users and their access keys. + +### Statistics Overview + +At the top of the page, you will find a dashboard summarizing the state of S3 user management: + + + + The total number of S3 users registered in the system. + + + +### Introduction + +The User table displays a list of all users. The table includes the following information: + +| Column | Description | +| :------------ | :---------------------------------------------------------------------------------------------------------------------------------- | +| **ID** | The unique identifier of the user. | +| **Name** | The display name of the user. | +| **Suspended** | Indicates whether the user account is suspended. | +| **Key** | The number of access keys associated with the user. Clicking the external link icon opens a detailed view of the [keys](#key-list). | + +### Create User + +You can create new users to access the object storage. + + + 1. Click the **Create** button. + 2. **ID**: Enter a unique identifier for the user. + 3. **Name**: Enter a display name for the user. + 4. **Suspend**: Toggle to create the user in a suspended state. + 5. Click **Confirm** to create the user. + + +### Manage Users + +You can modify or delete existing users using the **Actions** menu. + +#### Edit User + +Allows you to update the user's name or suspension status. + + + 1. Select **Edit** from the actions menu (pencil icon). + 2. Update the **Name** or **Suspend** status. + 3. Click **Confirm** to save changes. + + +#### Delete User + +Permanently removes a user. + + + 1. Select **Delete** from the actions menu (trash icon). + 2. Type the ID of the user to confirm deletion. + 3. Click **Confirm** to permanently delete the user. + + + + +### Manage Keys + +Access keys are used to authenticate requests to the object storage service. You can view and manage keys by clicking the external link icon in the **Key** column. + +#### Key List + +The key list displays the following information: + +| Column | Description | +| :------------- | :------------------------------------------- | +| **Access Key** | The access key ID. | + +#### Create Key + +You can generate new access keys for a user. + + + 1. Click the **Create** button within the key management view. + 2. The system will generate a new access key and secret key. + + +#### Delete Key + +Permanently removes an access key. + + + 1. Select **Delete** from the actions menu (trash icon). + 2. Confirm the deletion. + + + diff --git a/src/content/versions/v0.6.json b/src/content/versions/v0.6.json new file mode 100644 index 0000000..39452c9 --- /dev/null +++ b/src/content/versions/v0.6.json @@ -0,0 +1,121 @@ +{ + "sidebar": [ + { + "label": "Introduction", + "slug": "introduction", + "translations": { + "zh-Hant": "簡介" + } + }, + { + "label": "Getting Started", + "translations": { + "zh-Hant": "開始使用" + }, + "autogenerate": { + "directory": "getting-started" + } + }, + { + "label": "Basic", + "translations": { + "zh-Hant": "基本" + }, + "items": [ + { + "label": "Machines", + "translations": { + "zh-Hant": "機器" + }, + "slug": "basic/machines" + }, + { + "label": "Networking", + "translations": { + "zh-Hant": "網路" + }, + "slug": "basic/networking" + }, + { + "label": "Configuration", + "translations": { + "zh-Hant": "設定" + }, + "autogenerate": { + "directory": "basic/configuration" + } + } + ] + }, + { + "label": "Service", + "translations": { + "zh-Hant": "服務" + }, + "items": [ + { + "label": "Compute", + "translations": { + "zh-Hant": "計算" + }, + "slug": "service/compute" + }, + { + "label": "Models", + "translations": { + "zh-Hant": "模型" + }, + "slug": "service/models" + }, + { + "label": "Repositories", + "translations": { + "zh-Hant": "儲存庫" + }, + "slug": "service/repositories" + }, + { + "label": "Applications", + "translations": { + "zh-Hant": "應用" + }, + "autogenerate": { + "directory": "service/applications" + } + }, + { + "label": "Storage", + "translations": { + "zh-Hant": "儲存" + }, + "autogenerate": { + "directory": "service/storage" + } + }, + { + "label": "Settings", + "translations": { + "zh-Hant": "設定" + }, + "autogenerate": { + "directory": "service/settings" + } + } + ] + }, + { + "label": "Demos", + "translations": { + "zh-Hant": "演示範例" + }, + "autogenerate": { + "directory": "demos" + } + }, + { + "collapsed": false, + "items": [], + "label": "Symbol(StarlightOpenAPISidebarGroupsLabel)" + } + ] +} \ No newline at end of file