PolarDB:Mount with a SidecarSet

Prerequisites

Alibaba Cloud supports mounting by injecting a sidecar container into a Pod on a virtual node using a SidecarSet. For more information, see Inject a sidecar container into a Pod on a virtual node.

• SidecarSet: Install the SidecarSet dependencies in your cluster by following the SidecarSet documentation. Ensure that your ACK/ACS cluster allows privileged containers.

• Image: Pull the PolarDB Agent LakeBase image to your ACR repository, generate an image URL, and replace the <YOUR_LAKEBASE_IMAGE> placeholder in the following configurations with your URL.

  docker pull lakebase-registry.cn-beijing.cr.aliyuncs.com/lakebase/lakebase-client:latest

Placeholders

The YAML configurations in this topic use the following placeholders. Replace them with your actual values.

(Optional) Enable SSL

If you use PolarDB Agent LakeBase in a sandbox-like environment, we recommend that you enable SSL to enhance security and prevent network injection attacks.

1. On the details page of the destination cluster in the PolarDB console, click the AI Cache tab, click the destination PolarDB Agent LakeBase instance to open its details page, and then click the SSL Settings tab.

   1. In both the Primary Endpoint card and the Cluster Endpoint card, turn on the SSL Status switch. The SSL status changes from Off to On. Both addresses share the same certificate.

   2. Wait until the SSL status becomes On.

2. Click Download.

   1. Extract the downloaded certificate archive.

   2. Rename the .pem file to ca.pem.

3. Use the following Dockerfile to build your own image <YOUR_LAKEBASE_IMAGE> and push it to your ACR repository.

   FROM lakebase-registry.cn-beijing.cr.aliyuncs.com/lakebase/lakebase-client:latest
   
   COPY ca.pem /usr/local/bin/ca.pem

   docker build -t <YOUR_LAKEBASE_IMAGE> .

   Note

   When PolarDB Agent LakeBase is mounted with ca.pempg-ca.pem, make sure that SSL is enabled in the console.

Create a Secret

Create a YAML file, such as secret.yaml, with the following content. Replace the placeholders with your actual values.

apiVersion: v1
kind: Secret
metadata:
  name: <LAKEBASE_ID>
  namespace: <YOUR_NAMESPACE>
type: Opaque
stringData:
  name: "<LAKEBASE_ID>"
  metaurl: "<META_URL>"

Run the following command to create the Secret.

kubectl apply -f secret.yaml

Configure the SidecarSet

Choose a configuration method based on the Kubernetes version of your cluster.

# ============================================================
# Method 1: Declaration for native sidecar in Kubernetes v1.29 or later
# The SidecarSet injects the container through initContainers with restartPolicy: Always.
# Kubernetes natively ensures that the sidecar container starts before the application container.
# ============================================================
apiVersion: apps.kruise.io/v1alpha1
kind: SidecarSet
metadata:
  name: lakebase-sidecarset
spec:
  selector:
    matchLabels:
      inject-lakebase: "true"
      serverless.alibabacloud.com/virtual-node: "true"
  updateStrategy:
    type: NotUpdate

  initContainers:
    - name: lakebase-mount
      image: <YOUR_LAKEBASE_IMAGE>
      imagePullPolicy: Always
      restartPolicy: Always
      command:
        - sh
        - -c
        - |-
          /usr/local/bin/lakebase-client mount ${metaurl} /lakebase-data
      env:
        - name: JFS_FOREGROUND
          value: "1"
      envFrom:
        - secretRef:
            name: <LAKEBASE_ID>
      ports:
        - containerPort: 9567
          name: metrics
          protocol: TCP
      resources:
        limits:
          cpu: "2"
          memory: 4Gi
        requests:
          cpu: "2"
          memory: 4Gi
      securityContext:
        privileged: true
        runAsUser: 0
      startupProbe:
        exec:
          command:
            - sh
            - -c
            - "mount | grep /lakebase-data | grep PolarFS"
        initialDelaySeconds: 5
        periodSeconds: 3
        failureThreshold: 50
        successThreshold: 1
      volumeMounts:
        - name: lakebase-dir
          mountPath: /lakebase-data
          mountPropagation: Bidirectional

  volumes:
    - name: lakebase-dir
      emptyDir: {}

# ============================================================
# Method 2: Declaration for ACS custom sidecar in Kubernetes earlier than v1.29
# The SidecarSet injects the container through containers with the __IS_SIDECAR__ environment variable.
# ACS recognizes this flag and ensures that the sidecar container starts before other regular containers.
# ============================================================
apiVersion: apps.kruise.io/v1alpha1
kind: SidecarSet
metadata:
  name: lakebase-sidecarset
spec:
  selector:
    matchLabels:
      inject-lakebase: "true"
      serverless.alibabacloud.com/virtual-node: "true"
  updateStrategy:
    type: NotUpdate

  containers:
    - name: lakebase-mount
      image: <YOUR_LAKEBASE_IMAGE>
      imagePullPolicy: Always
      podInjectPolicy: BeforeAppContainer
      upgradeStrategy:
        upgradeType: ColdUpgrade
      shareVolumePolicy:
        type: disabled
      command:
        - sh
        - -c
        - |-
          /usr/local/bin/lakebase-client mount ${metaurl} /lakebase-data
      env:
        - name: JFS_FOREGROUND
          value: "1"
        - name: __IS_SIDECAR__
          value: "true"
      envFrom:
        - secretRef:
            name: <LAKEBASE_ID>
      ports:
        - containerPort: 9567
          name: metrics
          protocol: TCP
      resources:
        limits:
          cpu: "2"
          memory: 4Gi
        requests:
          cpu: "2"
          memory: 4Gi
      securityContext:
        privileged: true
        runAsUser: 0
      startupProbe:
        exec:
          command:
            - sh
            - -c
            - "mount | grep /lakebase-data | grep PolarFS"
        initialDelaySeconds: 5
        periodSeconds: 3
        failureThreshold: 50
        successThreshold: 1
      terminationMessagePath: /dev/termination-log
      terminationMessagePolicy: File
      volumeMounts:
        - name: lakebase-dir
          mountPath: /lakebase-data
          mountPropagation: Bidirectional

  volumes:
    - name: lakebase-dir
      emptyDir: {}

Run the following command to create the SidecarSet.

kubectl apply -f lakebase-sidecarset.yaml

(Optional) Ignore sidecar resources

To prevent the sidecar container from increasing the Pod's total resource request and ensure efficient resource sharing, configure the scheduler to ignore the sidecar's resource requests and limits. To do this, set the __IGNORE_RESOURCE__ environment variable to true in the container's env section in the lakebase-sidecarset.yaml file. For more information, see Configure the scheduler to ignore resources of a specific container.

    - name: __IGNORE_RESOURCE__
      value: "true"

Create an application Pod

After configuring the SidecarSet, create an application Pod. The following example uses Nginx as the application container.

apiVersion: v1
kind: Pod
metadata:
  name: lakebase-sidecarset-app
  namespace: <YOUR_NAMESPACE>
  labels:
    inject-lakebase: "true" # Required. This label allows the injection of the lakebase sidecar container.
    serverless.alibabacloud.com/virtual-node: "true" # Required if you use ECI or virtual nodes.
spec:
  containers:
    - name: nginx
      image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6
      imagePullPolicy: IfNotPresent
      command:
        - sh
        - -c
        - exec nginx -g 'daemon off;'
      ports:
        - containerPort: 80
          protocol: TCP
      resources:
        limits:
          cpu: "1"
          memory: 1Gi
        requests:
          cpu: "1"
          memory: 1Gi
      volumeMounts:
        - name: lakebase-dir
          mountPath: <MOUNT_POINT>
          subPath:  <SUB_DIR>
          mountPropagation: HostToContainer
  volumes:
    - name: lakebase-dir
      emptyDir: {}
  nodeSelector:
    type: virtual-kubelet
  tolerations:
    - key: virtual-kubelet.io/provider
      operator: Equal
      value: alibabacloud
      effect: NoSchedule

Run the following command to create the application Pod. After the Pod is running, access the container and navigate to the specified <MOUNT_POINT> directory to use PolarDB Agent LakeBase.

kubectl apply -f app.yaml

Appendix: Manual sidecar injection (Not recommended)

If you prefer to manage the sidecar container's lifecycle yourself instead of using the SidecarSet feature, you can manually inject the PolarDB Agent LakeBase mount container into your Pod as shown in the following example. For production environments, we recommend the SidecarSet method described earlier, as manual injection can increase maintenance overhead.

apiVersion: v1
kind: Pod
metadata:
  annotations: {}
  name: lakebase-sidecar-manual-app
  namespace: <YOUR_NAMESPACE>
spec:
  initContainers:
  - name: lakebase-mount
    image: <YOUR_LAKEBASE_IMAGE>
    imagePullPolicy: Always
    restartPolicy: Always
    command:
    - sh
    - -c
    - |-
      /usr/local/bin/lakebase-client mount ${metaurl} /lakebase-data
    env:
    - name: JFS_FOREGROUND
      value: "1"
    envFrom:
    - secretRef:
        name: <LAKEBASE_ID>
    ports:
    - containerPort: 9567
      name: metrics
      protocol: TCP
    resources:
      limits:
        cpu: "2"   
        memory: 4Gi
      requests:
        cpu: "2"
        memory: 4Gi
    securityContext:
      privileged: true
      runAsUser: 0
    startupProbe:
      exec:
        command:
        - sh
        - -c
        - "mount | grep /lakebase-data | grep PolarFS"
      initialDelaySeconds: 5
      periodSeconds: 3
      failureThreshold: 50
      successThreshold: 1
    terminationMessagePath: /dev/termination-log
    terminationMessagePolicy: File
    volumeMounts: # volumeMounts declaration. You must also declare it in the application container.
    - name: lakebase-dir
      mountPath: /lakebase-data
      mountPropagation: Bidirectional

  # This is an example application container.
  containers:
  - name: nginx
    image: anolis-registry.cn-zhangjiakou.cr.aliyuncs.com/openanolis/nginx:1.14.1-8.6
    imagePullPolicy: IfNotPresent
    ports:
    - containerPort: 80
      protocol: TCP
    resources:
      limits:
        cpu: "1"
        memory: 1Gi
      requests:
        cpu: "1"
        memory: 1Gi
    terminationMessagePath: /dev/termination-log
    terminationMessagePolicy: File
    volumeMounts: # volumeMounts declaration for the application container.
    - name: lakebase-dir
      mountPath: <MOUNT_POINT>
      subPath: <SUB_DIR>
      mountPropagation: HostToContainer
  dnsPolicy: ClusterFirst
  enableServiceLinks: true
  preemptionPolicy: PreemptLowerPriority
  priority: 0
  restartPolicy: Always
  schedulerName: default-scheduler
  securityContext: {}
  serviceAccount: default
  serviceAccountName: default
  terminationGracePeriodSeconds: 30
  tolerations:
  - effect: NoSchedule
    key: virtual-kubelet.io/provider
    operator: Equal
    value: alibabacloud
  - effect: NoExecute
    key: node.kubernetes.io/not-ready
    operator: Exists
    tolerationSeconds: 300
  - effect: NoExecute
    key: node.kubernetes.io/unreachable
    operator: Exists
    tolerationSeconds: 300
  volumes:
  - name: lakebase-dir
    emptyDir: {}