diff --git a/astro.config.mjs b/astro.config.mjs index 373716a..324a853 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -18,6 +18,7 @@ export default defineConfig({ logo: { src: './src/assets/logo.png' }, + favicon: '/logo.png', social: [ { icon: 'github', @@ -47,14 +48,14 @@ export default defineConfig({ }, { - label: 'basic', + label: 'Basic', translations: { 'zh-Hant': '基本' }, autogenerate: { directory: 'basic' } }, { - label: 'service', + label: 'Service', translations: { 'zh-Hant': '服務' }, diff --git a/public/logo.png b/public/logo.png new file mode 100644 index 0000000..cdd69ff Binary files /dev/null and b/public/logo.png differ diff --git a/src/assets/logo2.png b/src/assets/logo2.png new file mode 100644 index 0000000..0facec1 Binary files /dev/null and b/src/assets/logo2.png differ diff --git a/src/content/docs/getting-started/01-prerequisites.md b/src/content/docs/getting-started/01-prerequisites.mdx similarity index 67% rename from src/content/docs/getting-started/01-prerequisites.md rename to src/content/docs/getting-started/01-prerequisites.mdx index 9b5b63f..2dda5ab 100644 --- a/src/content/docs/getting-started/01-prerequisites.md +++ b/src/content/docs/getting-started/01-prerequisites.mdx @@ -3,6 +3,8 @@ title: Prerequisites description: Hardware and network requirements for running OtterScale. --- +import { Card, CardGrid, Aside, Tabs, TabItem, Badge } from '@astrojs/starlight/components'; + ## System Requirements Before installing OtterScale, ensure your environment meets the following specifications. @@ -13,7 +15,7 @@ Before installing OtterScale, ensure your environment meets the following specif | :-------- | :------------------------------ | | **OS** | **Ubuntu 24.04 LTS** (Required) | -### Hardware Specifications +### Hardware | Resource | Minimum Requirement | | :------------- | :----------------------- | @@ -33,16 +35,18 @@ Before installing OtterScale, ensure your environment meets the following specif The installation process requires outbound access to various external services. Please whitelist the following domains and ports. -### Core Infrastructure + + -| Service Group | Port(s) | Domains | -| :---------------------- | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Canonical Services** | TCP 443 (HTTPS)
TCP 80 (HTTP)\* | `api.charmhub.io`, `api.jujucharms.com`, `changelogs.ubuntu.com`, `charmhub.io`, `cloud-images.ubuntu.com`, `maas.ubuntu.com`, `images.maas.io`\*, `juju.is`, `jaas.ai`, `streams.canonical.com`, `objects.githubusercontent.com`, `contracts.canonical.com` | -| **Snap Store** | TCP 443 | `snapcraft.io`, `api.snapcraft.io`, `storage.snapcraftcontent.com`, `*.cdn.snapcraftcontent.com` | -| **Ubuntu Repos** | TCP 443, 80 | `archive.ubuntu.com`, `security.ubuntu.com`, `esm.ubuntu.com`, `ports.ubuntu.com`, `tw.archive.ubuntu.com` | -| **GitHub & OtterScale** | TCP 443, 80 | `otterscale.github.io`, `otterscale.com`, `github.com`, `raw.githubusercontent.com` | +| Service Group | Port(s) | Domains | +| :---------------------- | :---------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Canonical Services** | TCP 443 (HTTPS)
TCP 80 (HTTP)\* | `api.charmhub.io`, `api.jujucharms.com`, `changelogs.ubuntu.com`, `charmhub.io`, `cloud-images.ubuntu.com`, `maas.ubuntu.com`, `images.maas.io`\*, `juju.is`, `jaas.ai`, `streams.canonical.com`, `objects.githubusercontent.com`, `contracts.canonical.com` | +| **Snap Store** | TCP 443 | `snapcraft.io`, `api.snapcraft.io`, `storage.snapcraftcontent.com`, `*.cdn.snapcraftcontent.com` | +| **Ubuntu Repos** | TCP 443, 80 | `archive.ubuntu.com`, `security.ubuntu.com`, `esm.ubuntu.com`, `ports.ubuntu.com`, `tw.archive.ubuntu.com` | +| **GitHub & OtterScale** | TCP 443, 80 | `otterscale.github.io`, `otterscale.com`, `github.com`, `raw.githubusercontent.com` | -### Container Registries & Images + + | Registry | Port | Domains | | :----------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------- | @@ -52,10 +56,14 @@ The installation process requires outbound access to various external services. | **Red Hat / Quay** | TCP 443 | `registry.redhat.io`, `quay.io`, `registry.access.redhat.com` | | **Others** | TCP 443 | `registry.cn-hangzhou.aliyuncs.com` | -### AI & Helm Resources + + | Category | Port | Domains | | :-------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **HuggingFace** | TCP 443 | `huggingface.co`, `cdn-lfs.huggingface.co`, `cdn.huggingface.co` | | **Istio** | TCP 443 | `istio.io` | | **Helm Charts** | TCP 443 | `charts.jetstack.io`, `charts.bitnami.com`, `open-feature.github.io`, `prometheus-community.github.io`, `project-hami.github.io`, `helm.ngc.nvidia.com`, `llm-d.ai` | + + + diff --git a/src/content/docs/getting-started/02-installation.md b/src/content/docs/getting-started/02-installation.md deleted file mode 100644 index 71246c0..0000000 --- a/src/content/docs/getting-started/02-installation.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Installation -description: Step-by-step guide to installing OtterScale. ---- - -Follow the steps below to install and configure OtterScale. - -## Installation Process - -### 1. Start Services - -Run the following command to start the necessary services using Docker Compose: - -```bash -docker-compose up -d -``` - -### 2. Configure Installation - -Create an `install.cfg` file with the required configuration. You can use the following template: - -```bash title="install.cfg" -## MAAS DHCP Range IP -MAAS_DHCP_START_IP="192.168.197.216" -MAAS_DHCP_END_IP="192.168.197.219" - -## OtterScale Web IP -OTTERSCALE_WEB_IP="192.168.197.220" -``` - -Ensure that the IP addresses are correctly configured for your network environment. - -### 3. Run Installation Script - -Execute the installation script through the User Interface: - -1. Access the OtterScale UI. -2. Execute the `install.sh` script. diff --git a/src/content/docs/getting-started/02-installation.mdx b/src/content/docs/getting-started/02-installation.mdx new file mode 100644 index 0000000..03f1c8f --- /dev/null +++ b/src/content/docs/getting-started/02-installation.mdx @@ -0,0 +1,45 @@ +--- +title: Installation +description: Step-by-step guide to installing OtterScale. +--- + +import { Steps, Aside } from '@astrojs/starlight/components'; + +Follow the steps below to install and configure OtterScale. + + + +1. **Start Services** + + Run the following command to start the necessary services using Docker Compose: + + ```bash + docker-compose up -d + ``` + +2. **Configure Installation** + + Create an `install.cfg` file with the required configuration. You can use the following template: + + ```bash title="install.cfg" + ## MAAS DHCP Range IP + MAAS_DHCP_START_IP="192.168.197.216" + MAAS_DHCP_END_IP="192.168.197.219" + + ## OtterScale Web IP + OTTERSCALE_WEB_IP="192.168.197.220" + ``` + + + +3. **Run Installation Script** + + Execute the installation script through the User Interface: + + 1. Access the OtterScale UI. + 2. Execute the `install.sh` script. + + diff --git a/src/content/docs/getting-started/03-scope.md b/src/content/docs/getting-started/03-scope.md deleted file mode 100644 index 8d62583..0000000 --- a/src/content/docs/getting-started/03-scope.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Scope -description: Manage scopes in OtterScale. ---- - -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. Plan Selection - -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. Scope Details - -Fill in the following information to configure your new scope: - -#### Scope Name - -- **Label**: Scope Name ● -- **Description**: Enter a unique name for your scope. -- **Input**: Text field (Required). - -#### Machine Selection - -- **Label**: Machine ● -- **Description**: Select the physical machine to assign to this scope. -- **Input**: Dropdown menu. - - The dropdown lists available machines that are in the `Ready` status. - - Hovering over the info icon next to a machine name displays detailed hardware specifications (CPU, Memory, Storage, System info, etc.). - -#### Storage Devices - -- **Label**: Storage Devices ● -- **Description**: Select the block devices to be used by the scope. -- **Input**: Checkboxes. - - This section appears after you select a machine. - - It lists available non-boot block devices. - - Hovering over a device shows its model and capacity. - -#### Network Configuration - -- **Calico CIDR** (Optional): - - **Description**: The CIDR block for Calico networking. - - **Input**: Text field (e.g., `192.168.0.0/16`). -- **Virtual IP** (Optional): - - **Description**: The virtual IP address for the scope. - - **Input**: Text field (e.g., `192.168.1.1`). - -### 3. Creation Process - -Once you have filled in the details, click the **Create** button. The system will perform the following steps automatically: - -1. **Create Scope**: Initializes the scope record. -2. **Add Machine Tags**: Tags the selected machine. -3. **Commission Machine**: Configures the machine (SSH, networking, storage). -4. **Wait for Ready**: Waits for the machine to report a `Ready` status. -5. **Create Machine**: Associates the machine with the scope. -6. **Wait for Agent**: Waits for the agent to start on the machine. -7. **Create Node**: Finalizes the node creation with network and storage settings. - -You will see a loading indicator and status messages during this process. Once complete, a success message will appear. diff --git a/src/content/docs/getting-started/03-scope.mdx b/src/content/docs/getting-started/03-scope.mdx new file mode 100644 index 0000000..18e9006 --- /dev/null +++ b/src/content/docs/getting-started/03-scope.mdx @@ -0,0 +1,127 @@ +--- +title: Scope +description: Manage scopes in OtterScale. +--- + +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. **Wait for Ready**: Waits for the machine to report a `Ready` status. + + The `Ready` status is mandatory before any further actions can be taken. It confirms that: + + - Commissioning has completed successfully. + - The machine is free and available in the pool. + - It is eligible to be allocated and deployed with an operating system. + Attempting to deploy a machine that is not `Ready` (e.g., still commissioning or in a broken state) will fail. + +5. **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. + +6. **Wait for Agent**: Waits for the agent to start on the machine. + + This step monitors the Juju Agent status until it reports as `started`. This signifies that: + + - The OS installation is complete and the machine has booted. + - The Juju Agent is running and has successfully connected to the Juju Controller. + - The node is now online and ready to accept software deployments (Charms). + +7. **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/guides/install.md b/src/content/docs/guides/install.md index 9d56b89..0b3096f 100644 --- a/src/content/docs/guides/install.md +++ b/src/content/docs/guides/install.md @@ -8,13 +8,16 @@ description: A guide for installing Otterscale. ## System Requirements ### Operating System + - **Ubuntu 24.04 LTS** (Required) ### Hardware Requirements + - **Memory:** Minimum 8 GB RAM - **Disk Space:** Minimum 100 GB available storage ### Network Requirements + - At least one network interface with external internet connectivity - The installation script will check for network bridge `br-otters`: - If the bridge exists, it will be used @@ -27,6 +30,7 @@ The installation process requires access to various external services. Please en ### Canonical Services **TCP Port 443 (HTTPS):** + - api.charmhub.io - api.jujucharms.com - changelogs.ubuntu.com @@ -41,11 +45,13 @@ The installation process requires access to various external services. Please en - contracts.canonical.com **TCP Port 80 (HTTP):** + - images.maas.io ### Snap Package Management **TCP Port 443 (HTTPS):** + - snapcraft.io - api.snapcraft.io - storage.snapcraftcontent.com @@ -57,6 +63,7 @@ The installation process requires access to various external services. Please en ### Ubuntu Package Repositories **TCP Ports 443 and 80 (HTTPS/HTTP):** + - tw.archive.ubuntu.com - archive.ubuntu.com - ports.ubuntu.com @@ -66,6 +73,7 @@ The installation process requires access to various external services. Please en ### GitHub and OtterScale **TCP Ports 443 and 80 (HTTPS/HTTP):** + - otterscale.github.io - otterscale.com - raw.githubusercontent.com @@ -74,11 +82,13 @@ The installation process requires access to various external services. Please en ### Istio Service Mesh **TCP Port 443 (HTTPS):** + - istio.io ### Kubernetes and Container Registries **TCP Port 443 (HTTPS):** + - registry.k8s.io - k8s.gcr.io - ghcr.io @@ -88,6 +98,7 @@ The installation process requires access to various external services. Please en ### Docker Registry **TCP Port 443 (HTTPS):** + - auth.docker.io - auth.docker.com - login.docker.com @@ -102,16 +113,19 @@ The installation process requires access to various external services. Please en ### NVIDIA Container Registry **TCP Port 443 (HTTPS):** + - nvcr.io ### Alternative Container Registries **TCP Port 443 (HTTPS):** + - registry.cn-hangzhou.aliyuncs.com ### HuggingFace Model Repository **TCP Port 443 (HTTPS):** + - huggingface.co - cdn-lfs.huggingface.co - cdn.huggingface.co @@ -119,6 +133,7 @@ The installation process requires access to various external services. Please en ### Red Hat Registries **TCP Port 443 (HTTPS):** + - registry.redhat.io - quay.io - registry.access.redhat.com @@ -126,6 +141,7 @@ The installation process requires access to various external services. Please en ### Helm Chart Repositories **TCP Port 443 (HTTPS):** + - charts.jetstack.io (Cert-manager) - charts.bitnami.com (Bitnami charts) - open-feature.github.io (OpenFeature operator) diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index c743575..11d6a9f 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -15,7 +15,7 @@ hero: tagline: A unified platform for simplified compute, storage, and networking. image: - file: ../../assets/houston.webp + file: ../../assets/logo2.png actions: - text: Get Started link: /introduction/ diff --git a/src/content/docs/introduction.md b/src/content/docs/introduction.md deleted file mode 100644 index 2b5da66..0000000 --- a/src/content/docs/introduction.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Get Started -description: Get started with OtterScale. ---- - -OtterScale is a unified infrastructure management platform designed to simplify the deployment and operation of complex distributed systems. It integrates bare metal provisioning, container orchestration, and distributed storage into a single, cohesive interface. - -## 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 - -- **Scope Management**: logically isolate resources and manage access control for different teams or projects. -- **AI/LLM Readiness**: Optimized for high-performance computing with support for GPU acceleration and high-speed networking (InfiniBand/RoCE). -- **Multi-Tenancy**: Securely share infrastructure across multiple users while maintaining resource isolation. -- **Unified Interface**: A single pane of glass for monitoring and managing the entire stack, from metal to service. - -## Next Steps - -- [Check Prerequisites](/getting-started/01-prerequisites) -- [Create a Scope](/getting-started/03-scope) -- [Explore Basic Features](/basic/machines) diff --git a/src/content/docs/introduction.mdx b/src/content/docs/introduction.mdx new file mode 100644 index 0000000..0d99428 --- /dev/null +++ b/src/content/docs/introduction.mdx @@ -0,0 +1,78 @@ +--- +title: Introduction +description: Overview of OtterScale. +--- + +import { Card, CardGrid, LinkCard, Steps, Aside } from '@astrojs/starlight/components'; + +OtterScale is a **Hyper-Converged Infrastructure (HCI)** platform that unifies compute, storage, networking, and virtualization into a single, software-defined system. By collapsing traditional infrastructure silos, OtterScale simplifies deployment and management while delivering the scalability needed for modern enterprise workloads. + + + +## 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 + + + + Logically isolate resources and manage access control for different teams or projects. + + + Optimized for high-performance computing with support for GPU acceleration and high-speed + networking (InfiniBand/RoCE). + + + Securely share infrastructure across multiple users while maintaining resource isolation. + + + A single pane of glass for monitoring and managing the entire stack, from metal to service. + + + +## Next Steps + + + + + + diff --git a/src/content/docs/service/02-compute.md b/src/content/docs/service/02-compute.md index 8541213..0ce799e 100644 --- a/src/content/docs/service/02-compute.md +++ b/src/content/docs/service/02-compute.md @@ -1,19 +1,20 @@ --- -title: Compute (VM) +title: Compute description: Manage Virtual Machines. --- -The Compute section allows you to create and manage Virtual Machines (VMs). +The Compute section allows you to create and manage Virtual Machines (Virtual Machines). -## Creating a VM +## Creating a Virtual Machine + +To create a new Virtual Machine: -To create a new VM: 1. Go to the Compute section. -2. Click "Create VM". +2. Click "Create Virtual Machine". 3. Select the OS image, CPU, and RAM configuration. 4. Configure networking and storage. -5. Launch the VM. +5. Launch the Virtual Machine. -## Managing VMs +## Managing Virtual Machines -You can start, stop, restart, and delete VMs from this interface. +You can start, stop, restart, and delete Virtual Machines from this interface. diff --git a/src/content/docs/service/03-models.md b/src/content/docs/service/03-models.md index c41b520..460bf5c 100644 --- a/src/content/docs/service/03-models.md +++ b/src/content/docs/service/03-models.md @@ -1,5 +1,5 @@ --- -title: Models (LLM) +title: Models description: Manage LLM models in OtterScale. --- @@ -12,6 +12,7 @@ View available models, their status, and resource consumption. ## Deploying a Model To deploy a new model: + 1. Navigate to the Models section. 2. Select "Deploy Model". 3. Choose the model type and configuration.