Karmada Certificate Framework

This document provides a comprehensive description of the certificate framework in the Karmada system, including the organizational structure, purpose, and configuration recommendations for all certificate resources. The Karmada certificate framework defines the certificate system required for secure communication between components, clearly articulating how each component uses certificates for authentication and communication encryption. This document will help administrators understand Karmada's certificate architecture, correctly configure and manage the certificates required by components, and ensure the security of the entire system.

Note: Currently, when installing Karmada using the community-maintained hack/deploy-karmada.sh script, certificates are generated following the framework described in this document. Other installation methods—including karmadactl init, karmada-operator, and Helm—will align with this certificate standard in future releases. For more details about this change, see the issue: Karmada Self-Signed Certificate Content Standardization.

Karmada Root Certificate

The Karmada root certificate serves as the top of the certificate chain and is the issuer of all subsequent certificates. Certificates generated by various components in the system (such as API Server, Aggregated API Server, Webhook, ETCD, etc.) are signed by this root certificate, establishing a chain of trust.

Here is an example of the Karmada root certificate:

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            5a:f6:2d:21:a5:31:92:99:32:07:00:dd:8f:37:0a:c0:ae:02:2f:c1
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: CN=karmada
        Validity
            Not Before: %b %d %H:%M:%S %Y GMT
            Not After : %b %d %H:%M:%S %Y GMT
        Subject: CN=karmada
        Subject Public Key Info:
        X509v3 extensions:
            X509v3 Basic Constraints: critical
                CA:TRUE

Karmada API Server

Server Certificate

The Server Certificate for Karmada API Server is used to encrypt and authenticate communication between the karmada-apiserver and clients. This certificate ensures that the karmada-apiserver can securely provide its service interface, while allowing clients to verify the server's authenticity, preventing man-in-the-middle attacks.

Command Line Flags

Passed via the --tls-cert-file flag

Recommended CN and SAN Values

Subject: CN=system:karmada:karmada-apiserver
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE
            X509v3 Subject Alternative Name:
                DNS:karmada-apiserver.karmada-system.svc.cluster.local,
                DNS:karmada-apiserver.karmada-system.svc, DNS:localhost,
                IP Address:127.0.0.1, IP Address:${apiserver_service_ip_address}

ETCD Client Certificate

The ETCD Client Certificate for Karmada API Server is used for identity authentication when the karmada-apiserver accesses the ETCD data store. It ensures that only authorized API Server instances can read and write data in ETCD.

Command Line Flags

Passed via the --etcd-certfile flag

Recommended CN and SAN Values

Subject: O=system:masters, CN=system:karmada:karmada-apiserver-etcd-client
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE

Front Proxy Client Certificate

The Client Certificate for Front Proxy is used for communication authentication between the front proxy and karmada-apiserver. In Karmada's API aggregation architecture, the front proxy handles request forwarding from the aggregated API Server. This certificate ensures the security and trustworthiness of the request forwarding process.

Command Line Flags

Passed via the --proxy-client-cert-file flag

Recommended CN and SAN Values

Subject: CN=front-proxy-client
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE

Karmada Aggregated API Server

Server Certificate

The Server Certificate for Karmada Aggregated API Server is used for Karmada's API aggregation layer, allowing API extensions to be dynamically added to the core API Server. This certificate ensures the identity authentication of the Aggregated API Server and secures communication with other components. Through the karmada-aggregated-apiserver, Karmada can securely extend its API functionality.

Command Line Flags

Passed via the --tls-cert-file flag

Recommended CN and SAN Values

Subject: CN=system:karmada:karmada-aggregated-apiserver
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE
            X509v3 Subject Alternative Name:
                DNS:karmada-aggregated-apiserver.karmada-system.svc.cluster.local, 
                DNS:karmada-aggregated-apiserver.karmada-system.svc, DNS:localhost, 
                IP Address:127.0.0.1

Client Certificate

The Client Certificate for Karmada Aggregated API Server is used for identity authentication when the karmada-aggregated-apiserver component communicates with the karmada-apiserver as a client. It allows the Karmada Aggregated API Server component to securely access API services and perform necessary operations. This certificate ensures that Karmada Aggregated API Server requests are correctly identified and authorized.

Command Line Flags

Passed via the --kubeconfig flag containing the certificate

Recommended CN and SAN Values

Subject: O=system:masters, CN=system:karmada:karmada-aggregated-apiserver
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Subject Alternative Name:

ETCD Client Certificate

The ETCD Client Certificate for Karmada Aggregated API Server is used for identity authentication when the karmada-aggregated-apiserver accesses the ETCD data store. It ensures that the karmada-aggregated-apiserver can securely store and retrieve the state information of its extended API resources while maintaining appropriate access control.

Command Line Flags Passed via the --etcd-certfile flag

Recommended CN and SAN Values

Subject: O=system:masters, CN=system:karmada:karmada-aggregated-apiserver-etcd-client
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Subject Alternative Name:

Karmada Webhook

Server Certificate

The Server Certificate for Karmada Webhook is used to encrypt and authenticate communication between the karmada-webhook and the karmada-apiserver. The karmada-webhook is responsible for resource validation and admission control in Karmada, ensuring that all operations on resources comply with predefined rules.

Command Line Flags

Passed via the --cert-dir flag, automatically read from the directory

Recommended CN and SAN Values

Subject: CN=system:karmada:karmada-webhook
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE
            X509v3 Subject Alternative Name:
                DNS:karmada-webhook.karmada-system.svc.cluster.local, 
                DNS:karmada-webhook.karmada-system.svc, DNS:localhost, 
                IP Address:127.0.0.1

Client Certificate

The Client Certificate for Karmada Webhook is used for identity authentication when the karmada-webhook component communicates with the karmada-apiserver as a client. It allows the Webhook component to securely access API services and perform necessary operations. This certificate ensures that Webhook requests are correctly identified and authorized.

Command Line Flags

Passed via the --kubeconfig flag containing the certificate

Recommended CN and SAN Values

Subject: O=system:masters, CN=system:karmada:karmada-webhook
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE

Karmada Search

Server Certificate

The Server Certificate for Karmada Search is used to encrypt and authenticate communication between karmada-search and clients. karmada-search provides cross-cluster resource search functionality, enabling administrators to quickly retrieve and query resources distributed across multiple clusters.

Command Line Flags

Passed via the --tls-cert-file flag

Recommended CN and SAN Values

Subject: CN=system:karmada:karmada-search
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE
            X509v3 Subject Alternative Name:
                DNS:karmada-search.karmada-system.svc.cluster.local, 
                DNS:karmada-search.karmada-system.svc, DNS:localhost, 
                IP Address:127.0.0.1

Client Certificate

The Client Certificate for Karmada Search is used for communication authentication between karmada-search and karmada-apiserver. It allows the search service to securely query and retrieve cross-cluster resource information. This certificate ensures the security of search requests and proper control of data access permissions.

Command Line Flags

Passed via the --kubeconfig flag containing the certificate

Recommended CN and SAN Values

Subject: O=system:masters, CN=system:karmada:karmada-search
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE

ETCD Client Certificate

The ETCD Client Certificate for Karmada Search certificate is used for identity authentication when karmada-search accesses the ETCD data store. It allows karmada-search to securely retrieve resource information from ETCD while ensuring proper control of data access permissions.

Command Line Flags

Passed via the --etcd-certfile flag

Recommended CN and SAN Values

Subject: O=system:masters, CN=system:karmada:karmada-search-etcd-client
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE

Karmada Metrics Adapter

Server Certificate

The Server Certificate for Karmada Metrics Adapter is used to encrypt and authenticate communication between karmada-metrics-adapter and karmada-apiserver. karmada-metrics-adapter provides custom metrics API support, enabling Karmada to perform resource scheduling and auto-scaling based on custom metrics.

Command Line Flags

Passed via the --tls-cert-file flag

Recommended CN and SAN Values

Subject: CN=system:karmada:karmada-metrics-adapter
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE
            X509v3 Subject Alternative Name:
                DNS:karmada-metrics-adapter.karmada-system.svc.cluster.local, 
                DNS:karmada-metrics-adapter.karmada-system.svc, DNS:localhost, 
                IP Address:127.0.0.1

Client Certificate

The Client Certificate for Karmada Metrics Adapter is used for communication authentication between karmada-metrics-adapter and karmada-apiserver. It allows the metrics adapter to securely access and provide custom metrics APIs. This certificate ensures secure query of metrics data and permission control.

Command Line Flags

Passed via the --kubeconfig flag containing the certificate

Recommended CN and SAN Values

Subject: O=system:masters, CN=system:karmada:karmada-metrics-adapter
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE

Karmada Scheduler Estimator

Server Certificate

The Server Certificate for Karmada Scheduler Estimator is used to encrypt and authenticate communication between karmada-scheduler-estimator and both karmada-scheduler and karmada-descheduler. karmada-scheduler-estimator provides cluster load estimation for scheduling decisions, helping Karmada make optimal resource allocation decisions.

Command Line Flags

Passed via the --grpc-auth-cert-file flag

Recommended CN and SAN Values

Subject: CN=system:karmada:karmada-scheduler-estimator
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE
            X509v3 Subject Alternative Name:
                DNS:*.karmada-system.svc.cluster.local, DNS:*.karmada-system.svc, 
                DNS:localhost, 
                IP Address:127.0.0.1

ETCD

Server Certificate

The Server Certificate for ETCD is used to encrypt and authenticate communication between the ETCD server and clients. ETCD is Karmada's core data store, holding all cluster state information. This certificate is crucial for protecting the storage and access of this sensitive data, ensuring that only authorized components can read and write data in ETCD.

Command Line Flags

Passed via the --key-file= flag

Recommended CN and SAN Values

Subject: CN=system:karmada:etcd-server
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE
            X509v3 Subject Alternative Name:
                DNS:etcd.karmada-system.svc.cluster.local, DNS:etcd.karmada-system.svc, 
                DNS:etcd-client.karmada-system.svc.cluster.local, 
                DNS:etcd-client.karmada-system.svc, DNS:localhost, 
                IP Address:127.0.0.1

ETCD Client Certificate

The ETCD Client Certificate for ETCD is a key security credential for the Karmada ETCD service's self-health check and internal communication, ensuring the security and availability of the ETCD service.

Command Line Flags

When building the etcd container, use the following command in the container

etcdctl get /registry --prefix --keys-only  --endpoints https://127.0.0.1:2379  --cacert /etc/karmada/pki/etcd-client/ca.crt --cert /etc/karmada/pki/etcd-client/tls.crt --key /etc/karmada/pki/etcd-client/tls.key

Recommended CN and SAN Values

Subject: CN=system:karmada:etcd-etcd-client
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Subject Alternative Name:

Karmada Controller Manager

Client Certificate

The Client Certificate for Karmada Controller Manager is used for communication authentication between karmada-controller-manager and karmada-apiserver. The controller manager contains multiple control loops responsible for maintaining the desired state of the cluster. This certificate ensures that the controller can securely interact with the karmada-apiserver to get and update resource states.

Command Line Flags

Passed via the --kubeconfig flag containing the certificate

Recommended CN and SAN Values

Subject: O=system:masters, CN=system:karmada:karmada-controller-manager
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE

Karmada Scheduler

Client Certificate

The Client Certificate for Karmada Scheduler is used for communication authentication between karmada-scheduler and karmada-apiserver. The scheduler is responsible for deciding which member clusters resources should be allocated to, making it a core component of Karmada's multi-cluster management.

Command Line Flags

Passed via the --kubeconfig flag containing the certificate

Recommended CN and SAN Values

Subject: O=system:masters, CN=system:karmada:karmada-scheduler
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE

GRPC Certificate

The GRPC Certificate for Karmada Scheduler is used to encrypt and authenticate gRPC communication between karmada-scheduler and karmada-scheduler-estimator. karmada-scheduler uses this channel to obtain cluster load estimation information for scheduling decisions. This certificate ensures the secure transmission of these critical performance data.

Command Line Flags

Passed via the --scheduler-estimator-cert-file flag

Recommended CN and SAN Values

Subject: O=system:masters, CN=system:karmada:karmada-scheduler-grpc
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE

Karmada Descheduler

Client Certificate

The Client Certificate for Karmada Descheduler is used for communication authentication between karmada-descheduler and karmada-apiserver. The descheduler is responsible for optimizing existing resource allocations by rescheduling to improve overall cluster efficiency. This certificate ensures the security and permission control of descheduling operations.

Command Line Flags

Passed via the --kubeconfig flag containing the certificate

Recommended CN and SAN Values

Subject: O=system:masters, CN=system:karmada:karmada-descheduler
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE

GRPC Certificate

The GRPC Certificate for Karmada Descheduler is used to encrypt and authenticate gRPC communication between karmada-descheduler and karmada-scheduler-estimator. karmada-descheduler uses this channel to obtain cluster load information for scheduling decisions. This certificate ensures the secure transmission of these critical performance data.

Command Line Flags

Passed via the --scheduler-estimator-cert-file flag

Recommended CN and SAN Values

Subject: O=system:masters, CN=system:karmada:karmada-descheduler-grpc
Subject Public Key Info:
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
            X509v3 Basic Constraints: critical
                CA:FALSE