/ /

开始体验

Docs 主页

管理

Atlas Kubernetes Operator

开始体验

Docs 主页

管理

Atlas Kubernetes Operator

开始体验

快速入门

您可以使用 Atlas Kubernetes Operator 管理 Atlas 中的资源，而无需离开 Kubernetes。本教程演示如何使用 Atlas Kubernetes Operator 从 Kubernetes 配置文件在 Atlas 中创建第一个集群。

警告

多租户安全指导

切勿在多个租户之间共享单个 Atlas Kubernetes Operator 安装，即使他们使用不同的命名空间。共享操作符的租户可以使用跨命名空间引用来访问其他命名空间中的资源，包括提供对其他租户的 Atlas 配置或其他云资源的访问权限的秘密。要隔离租户，请为每个租户部署单独的 Atlas Kubernetes Operator 实例。

注意

您想从 Helm 开始吗？

要使用 Atlas Kubernetes Operator 从 Helm Charts 在 Atlas 中创建第一个集群，请参阅Helm Charts 快速入门。

先决条件

本教程要求：

An Atlas account. To create one, see Create an Atlas Account.
An Atlas organization and project. To create them, see Create a Project.
正在运行的 Kubernetes 集群，其节点运行 x86-64、AMD64 或 ARM64 架构的处理器。
kubectl 安装和配置与 Kubernetes 集群通信。
jq 1.6 或更高版本。
访问 GitHub 上的Atlas Kubernetes Operator项目：https://github.com/mongodb/mongodb-atlas-kubernetes

网络要求：

Kubernetes 节点必须通过端口 443 (HTTPS) 访问 Atlas，以便 Atlas Kubernetes Operator 创建和管理资源。
如果部署多节点副本集，则所有 Kubernetes Pod 之间必须打开端口 27017 (默认)。

步骤

重要

自定义资源不再默认删除对象

Atlas Kubernetes Operator使用自定义资源配置文件来管理Atlas配置，但从Atlas Kubernetes Operator2.0 开始，您在Kubernetes中删除的自定义资源不再（默认）在Atlas中删除。相反， Atlas Kubernetes Operator只是停止管理Atlas中的这些资源。 AtlasProject示例，如果您在Kubernetes中删除自定义资源，默认默认， Atlas Kubernetes Operator不再自动从Atlas中删除相应的项目。这种行为更改旨在帮助防止意外删除。要学习；了解详情，包括如何将此行为恢复为在Atlas Kubernetes Operator.2 0之前使用的默认，请参阅新默认值： Atlas Kubernetes2 Operator.0 中的删除保护。

同样，如果您使用Atlas Kubernetes Operator从Kubernetes中的Atlas项目中删除团队，则Atlas Kubernetes Operator不会从Atlas中删除团队。
显式定义所需的配置详细信息，以避免隐式使用默认Atlas配置值。在某些情况下，继承Atlas默认值可能会导致协调循环，从而阻止自定义资源实现 READY 状态。示例，在 AtlasDeployment 自定义资源中显式定义所需的自动伸缩行为（如所包含的示例所示）可确保自定义资源中的静态实例大小不会重复应用于已启用自动伸缩的Atlas部署。
autoScaling: diskGB: enabled: true compute: enabled: true scaleDownEnabled: true minInstanceSize: M30 maxInstanceSize: M40

注册 Atlas 帐户或登录。

安装Atlas Kubernetes Operator。

选择以下方法之一来安装Atlas Kubernetes Operator：

要使用Atlas CLI安装Atlas Kubernetes Operator ，运行以下命令：

重要

Atlas CLI 创建 API 密钥，但无法检测集群的出站 IP。使用 --ipAccessList 标志将 Kubernetes 集群的 IP 或 CIDR 块加入允许列表，以便 Atlas Kubernetes Operator 能与 Atlas 通信。

To create the API key, the authenticated user or service account must have Organization Owner access to the organization. Without this access, the command fails with an HTTP 401 Unauthorized error from POST /api/atlas/v2/orgs/<orgId>/apiKeys.

atlas kubernetes operator install --ipAccessList <IP_OR_CIDR> [options]

注意

要为 Atlas for 政府安装 Atlas Kubernetes Operator，将 --atlasGov 标志附加到前面的命令中。

此命令会自动执行以下操作：

在Atlas组织中创建新的API密钥。
Adds your provided IP/CIDR to the API key's IP access list.
通过从 GitHub 获取清单，将Atlas Kubernetes Operator安装到当前 kubectl 上下文中配置的 Kubernetes 集群中。

在运行命令之前验证活跃上下文，请运行 kubectl config current-context。要切换到另一个集群，请运行 kubectl config use-context <context-name>。

To learn more about the command syntax and parameters, see the Atlas CLI documentation for atlas kubernetes operator install.

要使用 kubectl 安装Atlas Kubernetes Operator ，请按照以下步骤操作：

将 <VERSION> 替换为最新版本号，然后运行以下命令之一：
- 如果您希望 Atlas Kubernetes Operator 监视 Kubernetes 集群中的所有命名空间，运行：
  kubectl apply -f https://raw.githubusercontent.com/mongodb/mongodb-atlas-kubernetes/refs/heads/main/releases/v<VERSION>/deploy/all-in-one.yaml
- 如果您希望 Atlas Kubernetes Operator 仅监视其命名空间，请安装 deploy/namespaced 目录中的配置文件：
  kubectl apply -f https://raw.githubusercontent.com/mongodb/mongodb-atlas-kubernetes/v<VERSION>/deploy/namespaced/crds.yaml
  kubectl apply -f https://raw.githubusercontent.com/mongodb/mongodb-atlas-kubernetes/v<VERSION>/deploy/namespaced/namespaced-config.yaml
为 Atlas Kubernetes Operator 创建凭证以向 Atlas 进行身份验证。选择以下选项之一：
- API Key: Create an API key with Organization Project Creator permissions by following the procedure in Grant Programmatic Access to an Organization.
- Service Account: Create a Service Account with the appropriate roles in your Atlas organization or project. To learn more, see Service Accounts Overview.

使用您的凭证创建连接秘钥。

创建并标记 Atlas Kubernetes Operator 用于验证 Atlas 的秘密。选择与您偏好的身份验证方法匹配的标签页：

请使用您的 API 密钥和组织ID运行以下命令：

kubectl create secret generic mongodb-atlas-operator-api-key \
    --from-literal="orgId=<atlas_organization_id>" \
    --from-literal="publicApiKey=<atlas_api_public_key>" \
    --from-literal="privateApiKey=<atlas_api_private_key>" \
    -n mongodb-atlas-system

kubectl label secret mongodb-atlas-operator-api-key atlas.mongodb.com/type=credentials -n mongodb-atlas-system

使用您的服务账户凭证和组织 ID 运行以下命令：

kubectl create secret generic mongodb-atlas-operator-service-account \
    --from-literal="orgId=<atlas_organization_id>" \
    --from-literal="clientId=<service_account_client_id>" \
    --from-literal="clientSecret=<service_account_client_secret>" \
    -n mongodb-atlas-system

kubectl label secret mongodb-atlas-operator-service-account atlas.mongodb.com/type=credentials -n mongodb-atlas-system

要了解有关创建服务账户的更多信息，请参阅使用服务账户配置 Atlas 访问。

如果使用外部密钥存储，则外部密钥经理会创建和托管 kubernetes secret。要了解更多信息，请参阅配置密钥存储。

创建 `AtlasProject` 自定义资源。

运行以下命令以创建AtlasProject自定义资源：

注意

以下示例未指定 spec.connectionSecretRef.name。如果未指定，Atlas Kubernetes Operator 将使用之前用凭证和组织 ID 设置的默认连接秘钥。

部署Atlas Kubernetes Operator自定义资源。

cat <<EOF | kubectl apply -f -
apiVersion: atlas.mongodb.com/v1
kind: AtlasProject
metadata:
  name: my-project
spec:
  name: Test Atlas Operator Project
  projectIpAccessList:
    - ipAddress: <your-ip-address-range>
      comment: "Adding your IP to Atlas access list"
EOF

创建 `AtlasDeployment` 自定义资源。

运行以下命令之一以创建AtlasDeployment自定义资源并创建集群：

付费层级：

cat <<EOF | kubectl apply -f -
apiVersion: atlas.mongodb.com/v1
kind: AtlasDeployment
metadata:
  name: my-atlas-cluster
spec:
  projectRef:
    name: my-project
  deploymentSpec:
    clusterType: REPLICASET
    name: "Test-cluster"
    tags:
      - key: "environment"
        value: "production"
    replicationSpecs:
      - zoneName: US-Zone
        regionConfigs:
          - electableSpecs:
              instanceSize: M10
              nodeCount: 3
            providerName: AWS
            regionName: US_EAST_1
            priority: 7
EOF

免费集群：

cat <<EOF | kubectl apply -f -
apiVersion: atlas.mongodb.com/v1
kind: AtlasDeployment
metadata:
  name: my-atlas-cluster
spec:
  projectRef:
    name: my-project
  deploymentSpec:
    clusterType: REPLICASET
    name: "Test-cluster"
    replicationSpecs:
      - regionConfigs:
          - regionName: US_EAST_1
            providerName: TENANT
            backingProviderName: AWS
            electableSpecs:
              instanceSize: M0
              nodeCount: 3
EOF

要创建无服务器实例，请参阅无服务器实例示例。

创建带有密码的 Kubernetes Secret，登录 Atlas 集群数据库。

将P@@ssword%替换为您的密码，然后运行以下命令：

kubectl create secret generic the-user-password --from-literal="password=P@@sword%"

kubectl label secret the-user-password atlas.mongodb.com/type=credentials

如果使用外部密钥存储，则外部密钥经理会创建和托管 kubernetes secret。要了解更多信息，请参阅配置密钥存储。

创建 `AtlasDatabaseUser` 自定义资源。

运行以下命令以创建AtlasDatabaseUser自定义资源：

注意

spec.passwordSecretRef 必须引用您之前创建的密码。

cat <<EOF | kubectl apply -f -
apiVersion: atlas.mongodb.com/v1
kind: AtlasDatabaseUser
metadata:
  name: my-database-user
spec:
  roles:
    - roleName: "readWriteAnyDatabase"
      databaseName: "admin"
  projectRef:
    name: my-project
  username: theuser
  passwordSecretRef:
    name: the-user-password
EOF

检查数据库用户的状态。

运行以下命令，直到收到True响应，这表明数据库用户已准备就绪：

注意

AtlasDatabaseUser 自定义资源等待集群准备就绪。创建新的免费集群需要不到 15 秒。创建新的 Flex 或 Dedicated集群最多可能需要 10 分钟。

kubectl get atlasdatabaseusers my-database-user -o=jsonpath='{.status.conditions[?(@.type=="Ready")].status}'

检索 Atlas Kubernetes Operator 创建的用于连接到集群的密钥。

复制以下命令：
重要
以下命令需要 jq 1.6 或更高版本。
kubectl get secret {my-project}-{my-atlas-cluster}-{my-database-user} -o json | jq -r '.data | with_entries(.value |= @base64d)';

对于自定义资源，用详细信息替换以下占位符：

`my-project`	指定`AtlasProject`自定义资源的`metadata`字段的值。
`my-atlas-cluster`	指定`AtlasDeployment`自定义资源的`metadata`字段的值。
`my-database-user`	指定`AtlasDatabaseUser`自定义资源的`metadata`字段的值。

运行命令。

注意

您的连接字符串将与以下示例不同。

{
   "connectionStringStandard": "mongodb://theuser:P%40%40sword%25@test-cluster-shard-00-00.peqtm.mongodb.net:27017,test-cluster-shard-00-01.peqtm.mongodb.net:27017,test-cluster-shard-00-02.peqtm.mongodb.net:27017/?ssl=true&authSource=admin&replicaSet=atlas-pk82fl-shard-0",
   "connectionStringStandardSrv": "mongodb+srv://theuser:P%40%40sword%25@test-cluster.peqtm.mongodb.net",
   "password": "P@@sword%",
   "username": "theuser"
 }

您可以在应用程序中使用此 Kubernetes Secret：

containers:
 - name: test-app
   env:
    - name: "CONNECTION_STRING"
      valueFrom:
        secretKeyRef:
          name: test-atlas-operator-project-test-cluster-theuser
          key: connectionStringStandardSrv

验证部署

程序完成后，在连接前确认集群已准备就绪。

检查点	验证步骤
自定义资源就绪	运行 `kubectl get atlasdeployment -n <your-namespace>`，并确认 `AtlasDeployment` 资源将 `READY` 条件显示为 `True`。
Atlas 中的集群健康	在 Atlas 用户界面中，确认集群以 `Active` 状态出现在项目中。
连接成功	Use the connection string from Atlas to connect with `mongosh` and confirm the cluster is reachable.

后续步骤

验证集群后，您可以：

配置访问控制：设置数据库用户和网络访问。要了解具体操作，请参阅开始使用 Atlas Kubernetes Operator。
设置备份：为集群配置云备份。要了解如何操作，请参阅程序。
创建 Atlas 搜索索引：对数据启用全文搜索。要了解如何操作，请参阅使用 Kubernetes 创建 Atlas 搜索索引。
尝试基于 Helm 的快速入门：从 Helm Charts 而不是配置文件部署集群。要了解如何操作，请参阅 Helm Charts 快速入门。

快速入门

先决条件

步骤

注册 Atlas 帐户或登录。

安装Atlas Kubernetes Operator。

使用您的凭证创建连接秘钥。

创建 AtlasProject 自定义资源。

创建 AtlasDeployment 自定义资源。

创建带有密码的 Kubernetes Secret，登录 Atlas 集群数据库。

创建 AtlasDatabaseUser 自定义资源。

检查数据库用户的状态。

检索 Atlas Kubernetes Operator 创建的用于连接到集群的密钥。

验证部署

后续步骤

创建 `AtlasProject` 自定义资源。

创建 `AtlasDeployment` 自定义资源。

创建 `AtlasDatabaseUser` 自定义资源。