From ff192be070c7c2188a332ce1d943d4dbce0ac131 Mon Sep 17 00:00:00 2001
From: Jasmeer Abdulvahid <jabdulvahid@nvidia.com>
Date: Wed, 27 May 2026 14:59:37 -0700
Subject: [PATCH] doc(helm): how to get client key and certs

---
 docs/provisioning/ingesting-hosts.md | 74 +++++++++++++++++++++++++++-
 1 file changed, 73 insertions(+), 1 deletion(-)

diff --git a/docs/provisioning/ingesting-hosts.md b/docs/provisioning/ingesting-hosts.md
index 5393eab462..945e6f6214 100644
--- a/docs/provisioning/ingesting-hosts.md
+++ b/docs/provisioning/ingesting-hosts.md
@@ -6,7 +6,7 @@ Once you have NVIDIA Infra Controller (NICo) up and running, you can begin inges
 
 Ensure you have the following prerequisites met before ingesting machines:
 
-1. You have the `carbide-admin-cli` command available: You can compile it from sources or you can use the pre-compiled binary. Another choice is to use a containerized version.
+1. You have the `carbide-admin-cli` command available: You can compile it from sources or you can use the pre-compiled binary. Another choice is to use a containerized version. You can also download it from the cluster; see next section for details.
 
 2. You can access the NICo site using the `carbide-admin-cli`.
 
@@ -21,6 +21,78 @@ Ensure you have the following prerequisites met before ingesting machines:
     - The host BMC username (typically this is the factory default username)
     - The host BMC password (typically this is the factory default password)
 
+## Get client key and certificate needed for carbide-admin-cli
+These can be generated from site vault. Follow these steps to generate them.
+### Prerequisites
+
+1. Check `additional_issuer_cns` (one-time per cluster)
+```
+kubectl  get configmap -n nico-system nico-api-config-files -o yaml |  grep -i "additional_issuer_cns"
+```
+Expected: `additional_issuer_cns = ["site-root"]`
+
+If it's empty, edit the configmap and set it, then restart:
+
+```bash
+kubectl -n nico-system edit configmap nico-api-config-files
+# under [auth.trust]: additional_issuer_cns = ["site-root"]
+
+kubectl rollout restart deployment/nico-api -n nico-system
+```
+
+2. Get the CLI binary - You can skip this step you already have carbide-admin-cli binary.
+```bash
+POD=$(kubectl -n nico-system get pods -l app.kubernetes.io/name=nico-api -o jsonpath='{.items[0].metadata.name}')
+kubectl -n nico-system cp   "${POD}:/opt/carbide/carbide-admin-cli"   /usr/local/bin/carbide-admin-cli
+chmod +x /usr/local/bin/carbide-admin-cli
+# verify that it is working 
+carbide-admin-cli
+```
+
+3. Issue a client cert from Vault
+```bash
+VAULT_TOKEN=$(kubectl -n vault get secret vaultroottoken -o jsonpath='{.data.token}' | base64 -d)
+kubectl -n vault exec vault-0 -- env VAULT_SKIP_VERIFY=true VAULT_TOKEN="$VAULT_TOKEN" \
+  vault write -format=json nicoca/issue/nico-cluster \
+  common_name="<FQDN for nico-api-endpoint>" \
+  ttl=720h > /tmp/issued.json
+```
+
+Replace `<FQDN for nico-api-endpoint>` appropriately which usually is `api-<ENVIRONMENT_NAME>.<SITE_DOMAIN_NAME>`
+
+4. Extract PEM files
+```bash
+cat /tmp/issued.json | jq -r '.data.private_key' > /path/to/client.key
+cat /tmp/issued.json | jq -r '.data.certificate' > /path/to/client.crt
+cat /tmp/issued.json | jq -r '.data.issuing_ca' >  /path/to/ca.crt
+```
+
+You can run admin cli commands as
+```bash
+carbide-admin-cli https://api-<ENVIRONMENT_NAME>.<SITE_DOMAIN_NAME> --forge-root-ca-path /path/to/ca.crt --client-cert-path /path/to/client.crt  --client-key-path /path/to/client.key <command> ...
+```
+Alternatively to shorten the command line you can create a file named `carbide_api_cli.json` in folder `$HOME/.config` and add the following content:
+```json
+{
+  "carbide_api_url": "https://api-<ENVIRONMENT_NAME>.<SITE_DOMAIN_NAME>:443",
+  "forge_root_ca_path": "/path/to/ca.crt",
+  "client_cert_path": "/path/to/client.crt",
+  "client_key_path": "/path/to/client.key"
+}
+
+```
+5. Add `/etc/hosts` entry
+
+If you have trouble resolving `api-<ENVIRONMENT_NAME>.<SITE_DOMAIN_NAME>` you have to map it to the LoadBalancer IP:
+
+```bash
+CARBIDE_LB_IP=$(kubectl -n nico-system get svc nico-api-external \
+  -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
+
+grep -q "api-<ENVIRONMENT_NAME>.<SITE_DOMAIN_NAME>" /etc/hosts || \
+  echo "$CARBIDE_LB_IP api-<ENVIRONMENT_NAME>.<SITE_DOMAIN_NAME>" | sudo tee -a /etc/hosts
+```
+
 ## Update Site 
 
 NICo requires knowledge of the current and desired BMC and UEFI credentials for hosts and DPUs. NICo will reset current crendtials to the desired credentials on the BMC and UEFI when ingesting a host. You can use these credentials when accessing the host or DPU BMC yourself, and NICo will use these credentials for its automated processes.