02. install-garm.md

Install garm

• Install garm
  • Prepare garm configuration
    • Examples
  • Prepare domain and service
  • Prepare Athenz and garm certificate
    • Get root CA certificate and save as "Athenz root CA certificate"
    • Create garm certificate
    • Add garm certificates as k8s secret
  • Apply the garm configuration

Prepare garm configuration

Below files are under /k8s/*.yaml

Examples

1. garm-config.yaml

       token:
       ... (Omitted) ...
         # athenz public key version
         key_version: v1.1
   
       ... (Omitted) ...
   
       map_rule:
         tld:
           name: garm
           platform:
             service_athenz_domains: 
               - athenz.garm.user
   
         ... (Omitted) ...
   
         admin_athenz_domain: athenz.garm.admin
   kind: ConfigMap
   metadata:
         ... (Omitted) ...

2. garm-extapi.yaml

   apiVersion: v1
   data:
     # ca-public-key: /etc/garm/ssl/k8s-ca.pem
     # server-p12: /etc/garm/ssl/ypki.p12
     athenz-domain: athenz.garm.user
     service-name: garm-service

3. deployments.yaml

   • comment out configurations not in use

   spec:
     template:
       spec:
         containers:
         - env:
           ... (Omitted) ...
   
           # - name: ca
           #   valueFrom:
           #     configMapKeyRef:
           #       key: ca-public-key
           #       name: garm-extapi
   
           ... (Omitted) ...

   • modify Docker Registry URL

           image: yahoojapan/garm:latest

4. service.yaml

   # please make sure the IP works in your k8s cluster
   # reminder this IP, it will be used later
   spec:
     clusterIP: 10.96.0.11

Prepare domain and service

1. Create athenz domain

   # sample domains
   
   # garm domain
   athenz.garm
   # garm sub-domain for k8s admin operation
   athenz.garm.admin
   # garm sub-domain for k8s user operation
   athenz.garm.user

2. Create service
3. Generate key pair for the service and register public key to Athenz
4. Save the private key as athenz.key

Prepare Athenz and garm certificate

Get root CA certificate and save as "Athenz root CA certificate"

Root CA depends on the Athenz server which Garm connects to. For example:

# Cybertrust
wget 'https://www.cybertrust.ne.jp/sureserver/download/root_ca/BCTRoot.txt' -O ./athenz_root_ca.key
# DigiCert
wget 'https://dl.cacerts.digicert.com/DigiCertHighAssuranceEVRootCA.crt' -O ./athenz_root_ca.key

Create garm certificate

# CA
openssl genrsa -out rootCA.key 4096
openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.crt
# (will be used in later part, keep it safe)

# server
# SAN should contains the same IP configured in `service.yaml` in previous part
# to check the garm IP, use `kubectl get svc --all-namespaces`, webhook use IP only
openssl genrsa -out garm.key 2048
CN='garm'
SAN='subjectAltName=IP.1:10.96.0.11,DNS.1:garm.athenz.com'
openssl req -new -sha256 -key garm.key -subj "/C=JP/ST=TK/O=YJ/CN=${CN}" -reqexts SAN -config <(cat /etc/ssl/openssl.cnf <(printf "\n[SAN]\n${SAN}")) -out garm.csr
openssl x509 -req -in garm.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial -out garm.crt -days 512 -sha256 -extfile <(cat /etc/ssl/openssl.cnf <(printf "\n[SAN]\n${SAN}")) -extensions SAN

# user certificate for k8s
openssl genrsa -out user.key 2048
openssl req -new -sha256 -key user.key -subj "/C=JP/ST=TK/O=YJ/CN=${CN}" -out user.csr
openssl x509 -req -in user.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial -out user.crt -days 512 -sha256

# checking
openssl req -in garm.csr -text -noout
openssl x509 -in garm.crt -text -noout

# get base64 encoding
# openssl base64 -in garm.crt | tr -d '\n'; echo ''

Add garm certificates as k8s secret

# private key for login athenz
ATHENZ_PRIVATE_KEY='./athenz.key'
# athenz root CA certificate
ATHENZ_ROOT_CERT='./athenz_root_ca.key'
# garm server certificate
GARM_SERVER_CERT='./garm.crt'
# private key for garm certificate
GARM_SERVER_KEY='./garm.key'

kubectl create secret generic garm-secret-ca -n kube-public \
  --from-file=athenz-private.key="${ATHENZ_PRIVATE_KEY}" \
  --from-file=athenz-root.crt="${ATHENZ_ROOT_CERT}" \
  --from-file=garm-server-key.pem="${GARM_SERVER_KEY}" \
  --from-file=garm-server-cert.pem="${GARM_SERVER_CERT}"

Apply the garm configuration

# please execute with the same order
kubectl apply -f garm-extapi.yaml
kubectl apply -f garm-config.yaml
kubectl apply -f deployments.yaml
kubectl apply -f service.yaml