Using Lookup Function

1. Reading Existing Resources

Resource Type	Function Syntax	Description	Notes
lookup	`lookup("v1", "Secret", "namespace", "name")`	Fetches a secret from the cluster	Requires appropriate RBAC permissions
lookup	`lookup("v1", "ConfigMap", "namespace", "name")`	Fetches a config map from the cluster	Useful for reading configuration values at runtime
lookup	`lookup("apps/v1", "Deployment", "namespace", "name")`	Fetches a deployment resource	Can be used to inspect existing deployments

Example: Reading a Secret

{{- $secret := lookup "v1" "Secret" "my-namespace" "my-secret" -}}
{{- if $secret -}}
  {{- $data := $secret.data -}}
  {{- range $key, $value := $data -}}
    {{- printf "%s: %s" $key (b64dec $value) | quote -}}
  {{- end -}}
{{- end -}}

Example: Reading a ConfigMap

{{- $configMap := lookup "v1" "ConfigMap" "my-namespace" "my-configmap" -}}
{{- if $configMap -}}
  {{- range $key, $value := $configMap.data -}}
    {{- printf "%s: %s" $key $value | quote -}}
  {{- end -}}
{{- end -}}

Note: The lookup function is evaluated at template rendering time, not during the Helm install/upgrade process.

2. Querying ConfigMaps

Property	Description	Example
lookup	Function to query ConfigMaps and Secrets in a Kubernetes cluster	`{{ lookup "v1/ConfigMap" "my-namespace/my-configmap" }}`
lookup.key	Key within the ConfigMap to retrieve	`{{ lookup "v1/ConfigMap" "my-namespace/my-configmap" "key1" }}`

Example: Retrieving ConfigMap Value

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  database.url: "jdbc:postgresql://db:5432/myapp"
  cache.ttl: "300"

Example: Using Lookup in Helm Template

config:
  databaseUrl: {{ lookup "v1/ConfigMap" "default/app-config" "database.url" }}
  cacheTTL: {{ lookup "v1/ConfigMap" "default/app-config" "cache.ttl" }}

Note: The lookup function is evaluated at template rendering time, not during chart installation.

Warning: Ensure the ConfigMap exists in the target namespace before using lookup, or it will return an empty result.

3. Querying Secrets

Function	Signature	Description	Example
lookup	`lookup("secret", "namespace", "name")`	Retrieves a Kubernetes secret value by name and namespace.	`lookup("secret", "default", "my-secret")`

Example: Retrieving Secret Value

apiVersion: v1
kind: Pod
metadata:
  name: example-pod
spec:
  containers:
    - name: example-container
      image: nginx
      env:
        - name: DB_PASSWORD
          value: {{ lookup("secret", "default", "db-secret") }}

Note: The lookup function is available in Helm v3.2.0+ and requires appropriate RBAC permissions to access secrets.

4. Checking Resource Existence

Function	Signature	Description	Notes
lookup	`lookup { "name": string, "kind": string, "apiVersion": string, "namespace": string }`	Looks up a resource in the cluster	Requires RBAC permissions to access resources

Example: Checking if a ConfigMap Exists

{{- $configMap := lookup &#123; "name": "my-config", "kind": "ConfigMap", "apiVersion": "v1", "namespace": .Release.Namespace &#125; -}}
{{- if $configMap -}}
ConfigMap exists: {{ $configMap.metadata.name }}
{{- else -}}
ConfigMap does not exist
{{- end -}}

Note: The lookup function is evaluated at template rendering time, not during chart installation.

Warning: Using lookup in templates can cause issues with helm template and helm lint due to cluster access requirements.

5. Reading Resource Fields

Field	Description	Example
metadata.name	Name of the resource	`my-app`
metadata.namespace	Namespace of the resource	`production`
spec.replicas	Number of replicas for deployment	`3`
spec.template.spec.containers[0].image	Image used by the first container	`nginx:1.21`
status.phase	Current phase of the pod	`Running`

Example: Accessing Resource Fields

{{- $resource := lookup "v1" "Pod" "default" "my-pod" -}}
{{- printf "Pod name: %s" $resource.metadata.name -}}

Note: The lookup function returns a nil value if the resource is not found, so always check for existence before accessing fields.

6. Using Lookup in Conditionals

Condition	Description	Example
lookup	Used to look up values in a map or object	`{{- $value := lookup "v1" "ConfigMap" "default" "my-configmap" }}<br>{{- $value.data.key }}`
hasKey	Checks if a key exists in a map or object	`{{- if hasKey $config "database" }}<br> Database URL: {{ $config.database.url }}<br>{{- end }}`
empty	Checks if a value is empty (zero-length string, nil, or empty map)	`{{- if not (empty $config.database.url) }}<br> URL: {{ $config.database.url }}<br>{{- end }}`

Example: Using Lookup in Conditionals

{{- $config := .Values.database }}<br>{{- if hasKey $config "url" }}<br>  Database URL: {{ $config.url }}<br>{{- else if lookup "v1" "ConfigMap" .Release.Namespace "db-config" }}<br>  {{- $cm := lookup "v1" "ConfigMap" .Release.Namespace "db-config" }}<br>  URL: {{ $cm.data.url }}<br>{{- end }}

7. Handling Missing Resources

Resource Type	Lookup Function	Description	Notes
ConfigMap	`lookup "v1" "ConfigMap"`	Retrieve a ConfigMap from the cluster	Use `default` to provide fallback value if not found
Secret	`lookup "v1" "Secret"`	Retrieve a Secret from the cluster	Use `default` to provide fallback value if not found
Service	`lookup "v1" "Service"`	Retrieve a Service from the cluster	Use `default` to provide fallback value if not found
Deployment	`lookup "apps/v1" "Deployment"`	Retrieve a Deployment from the cluster	Use `default` to provide fallback value if not found

Example: Using lookup with default value

{{- $configMap := lookup "v1" "ConfigMap" .Release.Namespace "my-configmap" | default (dict) -}}
{{- if $configMap -}}
data: {{ $configMap.data }}
{{- else -}}
data: {}
{{- end -}}

Note: The lookup function returns null if the resource does not exist, and default can be used to provide a fallback value.

Warning: The lookup function does not work in helm template without --validate flag. It is primarily intended for use in helm install or helm upgrade.

8. Querying Across Namespaces

Function	Signature	Description	Notes
lookup	`lookup <kind> <name> [<namespace>]`	Fetches a resource from the Kubernetes API server	Can query across namespaces if namespace is provided

Example: Querying a ConfigMap in a Different Namespace

{{- $configMap := lookup "v1" "ConfigMap" "my-namespace" "my-configmap" -}}
{{- if $configMap }}
data: {{ $configMap.data }}
{{- end }}

Note: The lookup function requires appropriate RBAC permissions to access resources in other namespaces.

Warning: Using lookup across namespaces can lead to performance issues if the namespace is not cached.

9. Understanding Performance Implications

Aspect	Description	Impact
Lookup Function Usage	Used to retrieve values from other resources (e.g., ConfigMaps, Secrets)	Can introduce latency if not cached or optimized
Resource Access	Each lookup requires a Kubernetes API call or cache hit	High frequency lookups may increase API server load
Template Evaluation	Evaluated at template render time, not during chart installation	May cause delays in rendering if complex logic is involved

Note: Frequent use of lookup in templates can lead to performance degradation due to repeated API calls.

Warning: Avoid using lookup inside loops or high-frequency template evaluations without caching strategies.

Best Practices for Performance

Cache lookup results where possible to reduce redundant API calls
Avoid lookup in tight loops or frequently evaluated templates
Use lookup sparingly and only when necessary for dynamic configuration

10. Understanding Security Implications

Note: The lookup function in Helm charts can introduce security risks if not used carefully, particularly when dealing with user-provided data or external inputs.

Aspect	Description	Security Considerations
Data Source	Lookup function retrieves data from Kubernetes API server or other sources.	Ensure that the data source is trusted and access is restricted to authorized users or services.
Input Validation	Lookup function can accept user-defined keys or values.	Validate all inputs to prevent injection attacks or unauthorized access to resources.
Access Control	Lookup function may access sensitive resources like secrets or configmaps.	Implement RBAC policies to restrict access to only necessary resources and namespaces.
Output Sanitization	Results from lookup can be used directly in templates or values.	Sanitize output to prevent unintended rendering or execution of malicious content.

Example: Secure Usage of Lookup Function

apiVersion: v1
kind: Pod
metadata:
  name: example-pod
spec:
  containers:
    - name: example-container
      image: nginx
      env:
        - name: SECRET_VALUE
          valueFrom:
            secretKeyRef:
              name: {{ lookup "v1" "Secret" .Release.Namespace "my-secret" | quote }}
              key: secret-key

Warning: Avoid using user-provided values directly in lookup keys without sanitization. This can lead to privilege escalation or data exposure.