dev-tools/charts/airflow/docs/service-account-token-examples.rst

 .. Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

 ..   http://www.apache.org/licenses/LICENSE-2.0

 .. Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

Service Account Token Volume Examples
=====================================

This document provides comprehensive examples for configuring Service Account Token Volumes
in the Apache Airflow Helm Chart. These examples demonstrate various security scenarios and
use cases for pod-launching executors.

Overview
--------

Service Account Token Volume configuration allows you to manually control how Kubernetes
service account tokens are mounted into pods launched by Airflow. This feature implements the
**Principle of Least Privilege** by providing tokens only to containers that require Kubernetes API access.

**Container-Specific Security Model:**

- **Scheduler Container**: Receives Service Account Token as it requires API access for pod management
- **Init Container**: No Service Account Token as it only performs database migrations
- **Sidecar Container**: No Service Account Token as it only performs log cleanup operations

**This feature is particularly useful for**:

- Compliance with security policies that restrict automatic token mounting
- Implementation of defense-in-depth security strategies
- Custom token expiration and audience configuration
- Compatibility with security policy engines like Kyverno
- Meeting compliance frameworks that mandate container-specific privilege assignment

Basic Configuration Examples
----------------------------

Default Automatic Token Mounting
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This is the default behavior that continues to work without any changes:

.. code-block:: yaml
   :caption: values.yaml

   scheduler:
     serviceAccount:
       automountServiceAccountToken: true  # Default value

Manual Token Volume Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Basic manual configuration that disables automatic mounting and enables manual token volume:

.. code-block:: yaml
   :caption: values.yaml

   scheduler:
     serviceAccount:
       automountServiceAccountToken: false
       serviceAccountTokenVolume:
         enabled: true

This configuration:

- Disables automatic service account token mounting at the ServiceAccount level
- Enables manual token volume mounting at the Pod level
- Uses default values for all other token volume settings

Security-Focused Examples
-------------------------

High-Security Environment
^^^^^^^^^^^^^^^^^^^^^^^^^

For environments requiring enhanced security with shorter token lifetimes:

.. code-block:: yaml
   :caption: values.yaml

   scheduler:
     serviceAccount:
       automountServiceAccountToken: false
       serviceAccountTokenVolume:
         enabled: true
         expirationSeconds: 1800  # 30 minutes instead of default 1 hour
         mountPath: /var/run/secrets/kubernetes.io/serviceaccount
         volumeName: secure-kube-access

**Security Benefits:**

- **Shorter token lifetime** reduces exposure window if compromised
- **Explicit control** over token mounting makes security intentional
- **Container isolation** as only scheduler container receives API access
- **Clear naming** for security auditing and compliance reporting

Kyverno Policy Compliance
^^^^^^^^^^^^^^^^^^^^^^^^^

Configuration that complies with Kyverno policies requiring ``automountServiceAccountToken: false``
(`Restrict Auto-Mount of Service Account Tokens in Service Account`_ and `Restrict Auto-Mount of Service Account Tokens`_):

.. _Restrict Auto-Mount of Service Account Tokens in Service Account: https://kyverno.io/policies/other/restrict-sa-automount-sa-token/restrict-sa-automount-sa-token/
.. _Restrict Auto-Mount of Service Account Tokens: https://kyverno.io/policies/other/restrict-sa-automount-sa-token/restrict-sa-automount-sa-token/

.. code-block:: yaml
   :caption: values.yaml

   scheduler:
     serviceAccount:
       automountServiceAccountToken: false  # Required by Kyverno policy
       serviceAccountTokenVolume:
         enabled: true
         expirationSeconds: 3600
         audience: "https://kubernetes.default.svc.cluster.local"

Custom Mount Path Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For applications that expect service account tokens at custom locations:

.. code-block:: yaml
   :caption: values.yaml

   scheduler:
     serviceAccount:
       automountServiceAccountToken: false
       serviceAccountTokenVolume:
         enabled: true
         mountPath: /custom/sa-token
         volumeName: custom-service-account-token
         expirationSeconds: 7200  # 2 hours

This configuration mounts the token at ``/custom/sa-token`` instead of the default location.

Executor-Specific Examples
--------------------------

KubernetesExecutor Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Optimal configuration for ``KubernetesExecutor`` with security focus:

.. code-block:: yaml
   :caption: values.yaml

   executor: KubernetesExecutor

   scheduler:
     serviceAccount:
       automountServiceAccountToken: false
       serviceAccountTokenVolume:
         enabled: true
         expirationSeconds: 3600
         mountPath: /var/run/secrets/kubernetes.io/serviceaccount
         volumeName: k8s-executor-token

   # Ensure RBAC permissions for KubernetesExecutor
   rbac:
     create: true

CeleryKubernetesExecutor Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Configuration for hybrid executor that launches both Celery workers and Kubernetes task pods:

.. code-block:: yaml
   :caption: values.yaml

   executor: CeleryKubernetesExecutor

   scheduler:
     serviceAccount:
       automountServiceAccountToken: false
       serviceAccountTokenVolume:
         enabled: true
         expirationSeconds: 5400  # 1.5 hours for longer-running tasks
         volumeName: hybrid-executor-token

   # Redis configuration for Celery
   redis:
     enabled: true

Multi-Environment Examples
--------------------------

Development Environment
^^^^^^^^^^^^^^^^^^^^^^^

Relaxed configuration for development with longer token lifetimes:

.. code-block:: yaml
   :caption: values-dev.yaml

   scheduler:
     serviceAccount:
       automountServiceAccountToken: false
       serviceAccountTokenVolume:
         enabled: true
         expirationSeconds: 14400  # 4 hours for development convenience
         mountPath: /var/run/secrets/kubernetes.io/serviceaccount

Production Environment
^^^^^^^^^^^^^^^^^^^^^^

Strict production configuration with enhanced security:

.. code-block:: yaml
   :caption: values-prod.yaml

   # Additional production security settings
   securityContexts:
     pod:
       runAsNonRoot: true
       runAsUser: 50000
       fsGroup: 0
     container:
       allowPrivilegeEscalation: false
       readOnlyRootFilesystem: true
       runAsNonRoot: true

   scheduler:
     serviceAccount:
       automountServiceAccountToken: false
       serviceAccountTokenVolume:
         enabled: true
         expirationSeconds: 1800   # 30 minutes for production security
         audience: "https://kubernetes.default.svc.cluster.local"
         volumeName: prod-airflow-token

.. note::

   Remember that it is a good practice to have the production configuration on the test environment to ensure
   reliable testing before moving changes to production.

Migration Examples
------------------

Gradual Migration from Automatic to Manual
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Test manual configuration alongside automatic (for validation):

   .. code-block:: yaml
      :caption: values-test.yaml

      scheduler:
        serviceAccount:
          automountServiceAccountToken: true   # Keep automatic for now
          serviceAccountTokenVolume:
            enabled: false                     # Disable manual for testing

2. Enable manual configuration while keeping automatic (transition phase):

   .. code-block:: yaml
      :caption: values-transition.yaml

      scheduler:
        serviceAccount:
          automountServiceAccountToken: true   # Still automatic
          serviceAccountTokenVolume:
            enabled: true                      # Test manual mounting
            expirationSeconds: 3600

3. Complete migration to manual-only:

   .. code-block:: yaml
      :caption: values-final.yaml

      scheduler:
        serviceAccount:
          automountServiceAccountToken: false  # Disable automatic
          serviceAccountTokenVolume:
            enabled: true                      # Use manual only
            expirationSeconds: 3600

Troubleshooting Examples
------------------------

Debug Configuration
^^^^^^^^^^^^^^^^^^^

Configuration with extended token lifetime for troubleshooting:

.. code-block:: yaml
   :caption: values-debug.yaml

   scheduler:
     serviceAccount:
       automountServiceAccountToken: false
       serviceAccountTokenVolume:
         enabled: true
         expirationSeconds: 86400  # 24 hours for debugging
         mountPath: /var/run/secrets/kubernetes.io/serviceaccount
         volumeName: debug-sa-token

   # Enable debug logging
   config:
     logging:
       logging_level: DEBUG

Validation Commands
^^^^^^^^^^^^^^^^^^^

Commands to validate the configuration is working correctly:

.. code-block:: bash

   # Check if the service account token is mounted correctly
   kubectl exec -it deployment/airflow-scheduler -- ls -la /var/run/secrets/kubernetes.io/serviceaccount/

   # Verify token content and expiration
   kubectl exec -it deployment/airflow-scheduler -- cat /var/run/secrets/kubernetes.io/serviceaccount/token | base64 -d

   # Check scheduler logs for authentication issues
   kubectl logs deployment/airflow-scheduler | grep -i "auth\|token\|permission"

   # Describe the scheduler pod to see volume mounts
   kubectl describe pod -l component=scheduler

Advanced Configuration Examples
-------------------------------

Custom Audience Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For environments requiring specific token audiences:

.. code-block:: yaml
   :caption: values.yaml

   scheduler:
     serviceAccount:
       automountServiceAccountToken: false
       serviceAccountTokenVolume:
         enabled: true
         audience: "https://my-custom-api-server.example.com"
         expirationSeconds: 3600

Multi-Cluster Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Configuration for multi-cluster deployments:

.. code-block:: yaml
   :caption: values-cluster-a.yaml

   scheduler:
     serviceAccount:
       automountServiceAccountToken: false
       serviceAccountTokenVolume:
         enabled: true
         audience: "https://cluster-a.k8s.example.com"
         volumeName: cluster-a-token
         expirationSeconds: 3600

Integration with External Security Tools
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Configuration compatible with external security scanning and policy tools:

.. code-block:: yaml
   :caption: values-security-compliant.yaml

   # Additional security annotations
   airflowPodAnnotations:
     security.policy/scanned: "true"
     security.policy/compliant: "service-account-token-manual"

   scheduler:
     serviceAccount:
       automountServiceAccountToken: false
       serviceAccountTokenVolume:
         enabled: true
         expirationSeconds: 1800  # Short-lived tokens
         mountPath: /var/run/secrets/kubernetes.io/serviceaccount
         volumeName: security-compliant-token

Best Practices Summary
----------------------

**Container Security:**

1. **Understand container roles**: Only the scheduler container requires Kubernetes API access
2. **Verify token isolation**: Ensure init and sidecar containers operate without service account tokens
3. **Implement least privilege**: Each container should receive only the minimum required permissions

**Configuration Management:**

1. **Always test** manual token configuration in non-production environments first
2. **Use shorter token lifetimes** around 1800-3600 seconds
3. **Set explicit audiences** when integrating with external systems
4. **Use descriptive volume names** for easier troubleshooting and security auditing

**Security Monitoring:**

1. **Monitor logs** for authentication issues after migration
2. **Document your configuration** for security auditing and compliance purposes
3. **Audit container permissions** regularly to ensure compliance with security policies
4. **Combine with other security measures** like Pod Security Standards and network policies

**Migration Strategy:**

1. **Plan gradual migration** from automatic to manual token mounting
2. **Validate functionality** of each container type after configuration changes
3. **Maintain backward compatibility** during transition periods

**Why This Approach is More Secure:**

1. **Reduced attack surface**: Containers without API access cannot be used to compromise the cluster
2. **Clear security boundaries**: Explicit definition of which containers have API privileges
3. **Compliance ready**: Meets requirements for container-specific privilege assignment
4. **Audit friendly**: Clear documentation of security controls for compliance reporting

For more detailed information, see the :doc:`production-guide` section on Service Account Token Volume Configuration.