2. 快速开始

2.1. 前提条件

在开始安装前，需确保已获取必要资源，若尚未获取或需要完整部署说明，请参考 3.1 安装。

软件包获取

本章节资源获取以沐曦软件中心为例，访问前请确保已提前获取相应资源下载权限。

核心组件包
- 包获取路径：在软件中心上方菜单栏中选择下载 → 软件栈，进入工具包页面，选择云平台工具中的metax-gpu-k8s进入下载页面。
- 下载命令：假设要获取 0.13.1 版本的核心组件包，示例命令如下：
```
# 实际命令应以下载页面为准
wget -O metax-gpu-k8s-package.0.13.1.tar.gz "https://metax-pub.oss-cn-shanghai.aliyuncs.com..."
```

MXMACA^® SDK 镜像包：

包获取路径：在软件中心菜单栏中选择下载 → 镜像，在镜像下载页面选择MXMACA。

下载命令：以 ubuntu20.04 系统、 amd64 架构的 3.2.1.4 版本为例，示例命令如下：

# 实际命令应以下载页面为准
# docker命令
docker login --username=<user_name> --password=<user_password> cr.metax-tech.com && docker pull cr.metax-tech.com/public-library/maca-native:3.2.1.4-ubuntu20.04-amd64

内核驱动镜像包：

包获取路径：在软件中心中选择下载 → 镜像，在镜像下载页面选择Cloud-Tools。

下载命令：以 amd64 架构的 3.2.1.12 版本为例，示例命令如下：

# 实际命令应以下载页面为准
docker login --username=<user_name> --password=<user_password> cr.metax-tech.com && docker pull cr.metax-tech.com/public-cloud-release/driver-image:3.2.1.12-amd64

2.2. 安装

将安装包 metax-gpu-k8s-package.0.13.1.tar.gz 解压：
```
tar -xzvf metax-gpu-k8s-package.0.13.1.tar.gz
```
解压后获取以下文件：
- metax-k8s-images.0.13.1.run：镜像资源包
- metax-operator-0.13.1.tgz：Operator Helm Chart
- metax-gpu-extensions-0.13.1.tgz：Extensions Helm Chart

推送镜像。

需要推送的镜像分别为核心组件镜像、 MXMACA^® SDK 镜像和内核驱动镜像。假设容器仓库服务器域名为 <DOMAIN>，用于存放沐曦Kubernetes组件镜像的项目名为 <PROJECT>。

核心组件镜像

# REGISTRY一般为<DOMAIN>/<PROJECT>
REGISTRY="IMAGE REGISTRY"
# 默认使用docker进行镜像推送
metax-k8s-images.0.13.1.run push $REGISTRY
# 使用nerdctl进行镜像推送
metax-k8s-images.0.13.1.run nerdctl push $REGISTRY

MXMACA^® SDK 镜像

# 给镜像重新打tag
$ docker tag cr.metax-tech.com/public-library/maca-native:3.2.1.4-ubuntu20.04-amd64 $REGISTRY/maca-native:3.2.1.4-ubuntu20.04-amd64
# 推送镜像到仓库
$ docker push $REGISTRY/maca-native:3.2.1.4-ubuntu20.04-amd64

内核驱动镜像

# 给镜像重新打tag
$ docker tag cr.metax-tech.com/public-cloud-release/driver-image:3.2.1.12-amd64 $REGISTRY/driver-image:3.2.1.12-amd64
# 推送镜像到仓库
$ docker push $REGISTRY/driver-image:3.2.1.12-amd64

推送Helm Charts。

helm push ./k8s/metax-operator-0.13.1.tgz oci://$REGISTRY

安装 GPU Operator。

# 离线安装（基于本地Helm Charts）
helm install ./k8s/metax-operator-0.13.1.tgz \
--create-namespace -n metax-operator \
--generate-name \
--wait \
--set registry=$REGISTRY
--set driver.payload.version=3.2.1.12-amd64
--set maca.payload.registry=$REGISTRY
--set maca.payload.images={"maca-native:3.2.1.4-ubuntu20.04-amd64"}

2.3. 运行一个 GPU 任务

编写 GPU 任务 YAML

创建 gpu-task.yaml，用户可参考如下示例编写作业yaml文件：

apiVersion: v1
kind: Pod
metadata:
  name: gpu-demo
spec:
  containers:
  - name: vector-add
    image: ubuntu:20.04
    command: [
        "bash",
        "-c",
        "cp -r /opt/maca/samples/0_Introduction/vectorAdd /home;
        cd /home/vectorAdd;
        mxcc -x maca vectorAdd.cpp -o vectorAdd --maca-path=/opt/maca;
        ./vectorAdd > log/vectoradd_exec_output.log;
        tail -f /dev/null",
    ]
    resources:
      limits:
        metax-tech.com/gpu: 1  # 申请 1 张GPU

部署并验证任务

部署任务:

kubectl apply -f gpu-task.yaml -n metax-operator

检查 Pod 状态，状态为 Running:

kubectl get pods -n metax-operator

查看运行结果：

kubectl logs pod gpu-demo -n metax-operator

(可选) MinimalMode下部署作业

MinimalMode不会部署驱动和私有运行时组件，因此用户需提前完成内核态驱动的安装，并且作业所使用的镜像必须包含或使用 MXMACA^® SDK。下面以 MXMACA^® 镜像包为例，创建 gpu-task.yaml，用户可参考如下示例编写作业yaml文件：

apiVersion: v1
kind: Pod
metadata:
  name: gpu-demo
spec:
  containers:
  - name: vector-add
    image: cr.metax-tech.com/library/maca-native:3.2.1.4-ubuntu20.04-amd64
    command: [
        "bash",
        "-c",
        "cp -r /opt/maca/samples/0_Introduction/vectorAdd /home;
        cd /home/vectorAdd;
        mxcc -x maca vectorAdd.cpp -o vectorAdd --maca-path=/opt/maca;
        ./vectorAdd > log/vectoradd_exec_output.log;
        tail -f /dev/null",
    ]
    resources:
      limits:
        metax-tech.com/gpu: 1  # 申请 1 张GPU