잡 스펙의 `identity` 블록

잡 스펙의 identity 블록

identity 블록은 태스크가 환경 변수 또는 파일을 통해 Workload Identity에 접근할 수 있게 해줘요. Nomad는 모든 워크로드에 기본 아이덴티티를 만들지만, 그것을 태스크에 노출하진 않아요. 그리고 Vault, Consul, OIDC 인증 같은 외부 애플리케이션과 함께 쓰려는 추가 아이덴티티도 설정할 수 있어요.

출처: 문서

본문

예를 들어, 다음은 기본 Workload Identity를 환경 변수와 파일로 태스크에 노출하고, 서드파티 OIDC 공급자용으로 구성된 두 번째 Workload Identity를 노출해요:

job "docs" {
  group "example" {
    task "api" {

      identity {
        env         = true
        file        = true
        filepath    = "local/example.jwt"

        # Restart on token renewal to get the new env var
        change_mode = "restart"
      }

      identity {
        name        = "example"
        aud         = ["oidc.example.com"]
        file        = true
        ttl         = "1h"

        # Send a HUP signal when the token file is updated
        change_mode   = "signal"
        change_signal = "SIGHUP"
      }

      # ...
    }
  }
}

매개변수 (Parameters)

• name (string: "default") - 워크로드 아이덴티티의 이름. 태스크마다 고유해야 해요. 태스크의 identity 블록 중 name 필드를 생략할 수 있는 것은 하나뿐이에요.

• aud ([]string: nil) - 워크로드 아이덴티티의 audience 필드. 기본이 아닌 아이덴티티에는 항상 설정해야 해요.

• change_mode (string: "noop") - 토큰이 변경될 때 Nomad가 취할 동작.

  • "noop" - 아무 조치도 취하지 않음. 태스크가 현재 토큰이 거부될 때만 토큰을 다시 로드하거나 자체 변경 감지를 구현하도록 선택할 수 있으므로 기본값이에요.
  • "restart" - 태스크를 재시작.
  • "signal" - 태스크에 설정 가능한 신호를 보냄. change_signal을 반드시 설정해야 해요.

• change_signal (string: "") - "SIGHUP" 또는 "SIGUSR1" 같은 문자열로 태스크에 보낼 신호. change_mode가 signal이면 이 옵션은 필수예요.

• env (bool: false) - true면 워크로드 아이덴티티가 태스크의 NOMAD_TOKEN 환경 변수로 제공돼요.

• file (bool: false) - true면 워크로드 아이덴티티가 secrets/nomad_token 경로를 통해 태스크 파일시스템에서 사용 가능해요. task.user 매개변수가 설정되어 있으면 토큰 파일은 그 사용자만 읽을 수 있어요. 그렇지 않으면 파일은 누구나 읽을 수 있지만 부모 디렉터리 권한으로 보호돼요.

• filepath (string: "") - 비어 있지 않고 file이 true라면, 워크로드 아이덴티티는 NOMAD_SECRETS_DIR 대신 태스크 작업 디렉터리를 기준으로 지정된 위치에서 사용 가능해요.

• ttl (string: "") - 만료되기 전 아이덴티티의 수명. 클라이언트는 대략 TTL의 절반 시점에 아이덴티티를 갱신해요. "30s"나 "1h" 같은 레이블 접미사로 지정해요. 기본 아이덴티티에는 TTL을 설정할 수 없어요. 기본이 아닌 아이덴티티에는 항상 TTL을 설정해야 해요.

• extra_claims []string: nil) - 워크로드 아이덴티티에 추가되는 추가 클레임. 이 클레임은 성공적으로 추가되려면 네임스페이스에 optional_extra_claim으로 정의되어 있어야 해요.

Task API

워크로드 아이덴티티를 Nomad의 Task API와 결합하면 태스크가 Nomad API에 접근하도록 하는 데 편리해요.

Consul용 워크로드 아이덴티티 (Workload identities for Consul)

Consul에 접근해야 하는 잡은 인증에 Nomad 워크로드 아이덴티티를 사용할 수 있어요. 이 아이덴티티들은 Consul에 접근할 태스크 또는 서비스 안에 추가 identity 블록으로 지정돼요.

consul.service_identity와 consul.task_identity 에이전트 설정을 사용해 Nomad 서버가 Consul용 기본 아이덴티티를 자동으로 추가하도록 구성할 수 있어요. 잡 등록 시 Nomad 서버는 consul 블록이 있는 태스크와 Consul 서비스 공급자를 사용하는 서비스에 기본 아이덴티티를 포함하도록 업데이트해요.

template 블록을 포함하는 잡 스펙에는 기본 아이덴티티가 제공되지 않는데, Nomad가 템플릿 데이터의 내용을 해석할 수 없기 때문이에요. Consul에 필요한 아이덴티티는 잡 스펙에 직접 지정해야 해요.

이 아이덴티티들을 잡에 직접 지정할 수도 있어요. 제공되면 Nomad 서버에 구성된 기본 아이덴티티를 덮어써요. 태스크용 아이덴티티는 consul_<cluster name> 패턴을 따르는 name을 가져야 해요. 서비스용 아이덴티티는 name을 지정할 필요가 없어요.

Nomad Community Edition에서는 <cluster_name>이 항상 default이므로 태스크 아이덴티티 이름은 consul_default가 되어야 해요.

경고

Nomad Enterprise는 여러 Consul 클러스터를 지원해요. cluster_name 값은 태스크의 consul.cluster 매개변수 값과 같아야 해요.

자세한 내용은 Consul 통합 문서의 Nomad 워크로드 아이덴티티 섹션을 참고하세요.

job "httpd" {
  group "httpd" {
    consul {}

    network {
      port "http" {}
    }

    service {
      provider = "consul"
      name     = "httpd"
      port     = "http"

      identity {
        aud = ["consul.io"]
        ttl = "1h"
      }
    }

    task "httpd" {
      driver = "docker"

      config {
        image   = "busybox:1.36"
        command = "httpd"
        args    = ["-f", "-p", "${NOMAD_PORT_http}"]
        ports   = ["http"]
      }

      identity {
        name = "consul_default"
        aud  = ["consul.io"]
        ttl  = "1h"
      }
    }
  }
}

job "httpd" {
  group "httpd" {
    consul {
      cluster = "prod"
    }

    network {
      port "http" {}
    }

    service {
      provider = "consul"
      name     = "httpd"
      port     = "http"

      identity {
        aud = ["consul.io"]
        ttl = "1h"
      }
    }

    task "httpd" {
      driver = "docker"

      config {
        image   = "busybox:1.36"
        command = "httpd"
        args    = ["-f", "-p", "${NOMAD_PORT_http}"]
        ports   = ["http"]
      }

      identity {
        name = "consul_prod"
        aud  = ["consul.io"]
        ttl  = "1h"
      }
    }
  }
}

Vault용 워크로드 아이덴티티 (Workload identities for Vault)

Vault에 접근해야 하는 잡은 인증에 Nomad 워크로드 아이덴티티를 사용할 수 있어요. 이 아이덴티티들은 Vault에 접근할 태스크 안에 추가 identity 블록으로 지정돼요.

vault.default_identity 에이전트 설정을 사용해 Nomad 서버가 Vault용 기본 아이덴티티를 자동으로 추가하도록 구성할 수 있어요. 잡 등록 시 Nomad 서버는 vault 블록이 있는 태스크에 기본 아이덴티티를 포함하도록 업데이트해요.

이 아이덴티티들을 잡에 직접 지정할 수도 있어요. 제공되면 Nomad 서버에 구성된 기본 아이덴티티를 덮어써요. 아이덴티티 name은 vault_<cluster name> 패턴을 따라야 해요.

Nomad Community Edition에서는 <cluster_name>이 항상 default이므로 아이덴티티 이름은 vault_default가 되어야 해요.

경고

Nomad Enterprise는 여러 Vault 클러스터를 지원해요. 클러스터 이름은 태스크의 vault.cluster 매개변수 값과 같아야 해요.

자세한 내용은 Vault 통합 문서의 Nomad Workload Identities 섹션을 참고하세요.

job "mongo" {
  namespace = "default"

  group "db" {
    network {
      port "db" {
        to = 27017
      }
    }

    task "mongo" {
      driver = "docker"

      config {
        image = "mongo:7"
        ports = ["db"]
      }

      vault {}

      identity {
        name = "vault_default"
        aud  = ["vault.io"]
        ttl  = "1h"
      }

      template {
        data        = <<EOF
{{with secret "kv/data/default/mongo/config"}}
MONGO_INITDB_ROOT_USERNAME=root
MONGO_INITDB_ROOT_PASSWORD={{.Data.data.root_password}}
{{end}}
EOF
        destination = "secrets/env"
        env         = true
      }
    }
  }
}

job "mongo" {
  namespace = "default"

  group "db" {
    network {
      port "db" {
        to = 27017
      }
    }

    task "mongo" {
      driver = "docker"

      config {
        image = "mongo:7"
        ports = ["db"]
      }

      vault {
        cluster = "prod"
      }

      identity {
        name = "vault_prod"
        aud  = ["vault.io"]
        ttl  = "1h"
      }

      template {
        data        = <<EOF
{{with secret "kv/data/default/mongo/config"}}
MONGO_INITDB_ROOT_USERNAME=root
MONGO_INITDB_ROOT_PASSWORD={{.Data.data.root_password}}
{{end}}
EOF
        destination = "secrets/env"
        env         = true
      }
    }
  }
}

더 알아보기 (Learn more)

• Workload Identity
• Task API
• Consul 워크로드 아이덴티티
• Vault 워크로드 아이덴티티