All Products
Search

This Product

    Simple Log Service:Use CRs to manage Logtail configurations

    Document Center

    Simple Log Service:Use CRs to manage Logtail configurations

    Last Updated:Aug 26, 2026

    Simple Log Service defines two Kubernetes CRDs—AliyunPipelineConfig and AliyunLogConfig—that let you manage Logtail configurations as CustomResources (CRs).

    Overview

    A CRD extends the Kubernetes API to define custom resource types. Each CR is an instance of a CRD. Extend the Kubernetes API with CustomResourceDefinitions.

    To manage Logtail configurations with CRs, connect to your Kubernetes cluster, authenticate, and submit a YAML file to the kube-apiserver to create a CR.

    Warning

    If you create a Logtail configuration through a CR, always update it through the CR. Changes made in the SLS console do not sync back to the CR.

    Implementation of CR-based Logtail configuration management

    image

    1. SLS creates a Deployment that installs alibaba-log-controller, which monitors changes to the AliyunLogConfig CRD.

    2. When you create, update, or delete an AliyunLogConfig CR through kubectl or other tools, alibaba-log-controller detects the change and sends the corresponding request to SLS—for example, updating the Logtail configuration.

    CRDs

    SLS provides two CRDs for managing Logtail configurations in Kubernetes: AliyunPipelineConfig and AliyunLogConfig. The following table compares their capabilities.

    Important

    AliyunPipelineConfig requires Logtail 0.5.1 or later.

    CRD

    AliyunPipelineConfig (recommended)

    AliyunLogConfig

    ApiGroup

    telemetry.alibabacloud.com/v1alpha1

    log.alibabacloud.com/v1alpha1

    CRD resource name

    ClusterAliyunPipelineConfig

    AliyunLogConfig

    Scope

    Cluster

    Namespace

    Logtail configuration format

    Equivalent to LogtailPipelineConfig

    Equivalent to LogtailConfig

    Cross-region capability

    Supported

    Supported

    Cross-account capability

    Supported

    Supported

    Webhook-related parameter verification

    Supported

    Not supported

    Configuration conflict detection

    Supported

    Supported (Logtail 0.5+)

    Configuration difficulty

    Relatively low

    Relatively high

    Observability configuration

    The Status field includes error details, update time, the previously applied Logtail configuration, and when it was applied.

    The Status field contains the error code and error message.

    Troubleshoot 404 errors after a CRD is deleted

    If creating or updating a Logtail configuration fails with no matches for kind "ClusterAliyunPipelineConfig" or the server could not find the requested resource, the ClusterAliyunPipelineConfig CRD may have been accidentally deleted.

    Troubleshooting steps

    1. Check whether the CRD still exists:

      kubectl get crd | grep ClusterAliyunPipelineConfig

      If no output is returned, the CRD has been deleted.

    2. Reinstall LoongCollector to restore the CRD:

      helm upgrade loongcollector loongcollector/loongcollector -n kube-system --reuse-values

      Alternatively, apply the CRD YAML directly:

      kubectl apply -f crd.yaml

    3. Verify that the CRD has been restored:

      kubectl get crd | grep ClusterAliyunPipelineConfig

    4. Verify that you can create Logtail configurations again:

      kubectl apply -f your-pipeline-config.yaml
    Note

    The CRD is managed by the crds directory of the LoongCollector Helm chart. Restarting loongcollector-operator does not recreate the CRD; you must restore it with helm upgrade or kubectl apply. Deleting the CRD also deletes all existing ClusterAliyunPipelineConfig resources.