garm-functional-overview.md

Garm Functional Overview

• Garm Functional Overview
  • Parse k8s resources
  • Map resources
  • Subsitute Athenz domain & principal
  • Filter k8s request
  • Select Athenz domain
  • Create Athenz assertion - P.S. during mapping

Parse k8s resources

1. K8s authorization attributes
   1. ResourceAttributes
      • ResourceAttributes webhook.go
      • ResourceAttributes struct
   2. NonResourceAttributes
      • NonResourceAttributes webhook.go
      • NonResourceAttributes struct
2. garm resource attributes
   1. var namespace, verb, group, resource, name string

Map resources

• verb
  • config.yaml, map_rule.tld.platform.verb_mappings
  • key-value mapping
• resource
  • config.yaml, map_rule.tld.platform.resource_mappings
  • key-value mapping
• group
  • is "" if map_rule.tld.platform.api_group_control == false
  • config.yaml, map_rule.tld.platform.api_group_mappings
  • key-value mapping
• name
  • is "" if map_rule.tld.platform.resource_name_control == false
  • config.yaml, map_rule.tld.platform.resource_name_mappings
  • key-value mapping

Subsitute Athenz domain & principal

• Map env. variable in Athenz service domain
  • expectation
    1. split by .
    2. for each token matches _.*_, subsitute with env. variable (except _namespace_)
  • example
    • _k8s_cluster_._namespace_.athenz.service.domain => SANDBOX._namespace_.athenz.service.domain
      • config.GetActualValue("k8s_cluster") == "SANDBOX"
• Map namespace in Athenz admain (both admin & service domain)
  • expectation
    1. subsitute _namespace_ string in map_rule.tld.platform.admin_athenz_domain with garm resource attributes namespace
  • example
    • athenz.domain._namespace_ => athenz.domain.kaas_namespace
      • namespace = kaas_namespace
• Map k8s user to Athenz principal
  • expectation
    1. remove service_account_prefixes
    2. subsitute namespace
    3. subsitute :
    4. if service account, prepend athenz_service_account_prefix
    5. if not service account, prepend athenz_user_prefix
  • example
    • service_a:_namespace_:k8s_user => domain_a.k8s.kaas_namespace.k8s_user
      • service_account_prefixes = []string{"service_a"}
      • athenz_service_account_prefix = "domain_a.k8s."
      • namespace = kaas_namespace
    • service_b:service_c:k8s_user => domain_b.serviceaccount.service_c.k8s_user
      • service_account_prefixes = []string{"service_b", "service_c"}
      • athenz_service_account_prefix = "domain_b.k8s."
    • service_b:k8s_user => domain_c.k8s.k8s_user
      • service_account_prefixes = []string{"service_a", "service_b"}
      • athenz_service_account_prefix = "domain_c.k8s."
    • k8s_user => user.k8s_user
      • athenz_user_prefix = "user."

P.S. It may be easier to read the code directly. createAthenzDomains(), GetAdminDomain(), BuildDomainsFromNamespace(), PrincipalFromUser()

Filter k8s request

• in black_list AND NOT in white_list => directly reject
  • config.yaml, map_rule.tld.platform.black_list & map_rule.tld.platform.white_list
• Matching logic
  • create rule RegExp for matching
    • 
  • Garm resource attribute is serialized before matching with the rule RegExp.
• Example
  • RequestInfo{ Verb: "get", Namespace: "kube-system", APIGroup: "*", Resource: "secrets", Name: "alertmanager"} => check with Athenz
    • black_list contains RequestInfo{ Verb: "*", Namespace: "kube-system", APIGroup: "*", Resource: "*", Name: "*"}.
    • white_list contains RequestInfo{ Verb: "get", Namespace: "kube-system", APIGroup: "*", Resource: "secrets", Name: "alertmanager"}.
  • RequestInfo{ Verb: "get", Namespace: "kube-system", APIGroup: "*", Resource: "secrets", Name: "my-secret"} => directly reject
    • black_list contains RequestInfo{ Verb: "*", Namespace: "kube-system", APIGroup: "*", Resource: "*", Name: "*"}.
    • white_list ONLY contains RequestInfo{ Verb: "get", Namespace: "kube-system", APIGroup: "*", Resource: "secrets", Name: "alertmanager"}.

Select Athenz domain

• in admin_access_list => use admin domain
  • config.yaml, map_rule.tld.platform.admin_access_list
• Matching logic
  • same as above

Create Athenz assertion

P.S. during mapping

• Athenz service domain
  • 
• Athenz admin domain (2 requests to Athenz, OR logic, any one is allowed implies the action is allowed.)
  •