github.com/cilium/cilium@v1.16.2/Documentation/operations/performance/scalability/identity-relevant-labels.rst (about) 1 .. only:: not (epub or latex or html) 2 3 WARNING: You are looking at unreleased Cilium documentation. 4 Please use the official rendered version released here: 5 https://docs.cilium.io 6 7 .. _identity-relevant-labels: 8 9 ********************************* 10 Limiting Identity-Relevant Labels 11 ********************************* 12 13 We recommend that operators with larger environments limit the set of 14 identity-relevant labels to avoid frequent creation of new security identities. 15 Many Kubernetes labels are not useful for policy enforcement or visibility. A 16 few good examples of such labels include timestamps or hashes. These labels, 17 when included in evaluation, cause Cilium to generate a unique identity for each 18 pod instead of a single identity for all of the pods that comprise a service or 19 application. 20 21 By default, Cilium considers all labels to be relevant for identities, with the 22 following exceptions: 23 24 =================================================== ========================================================= 25 Label Description 26 --------------------------------------------------- --------------------------------------------------------- 27 ``any:!io.kubernetes`` Ignore all ``io.kubernetes`` labels 28 ``any:!kubernetes\.io`` Ignore all other ``kubernetes.io`` labels 29 ``any:!statefulset\.kubernetes\.io/pod-name`` Ignore ``statefulset.kubernetes.io/pod-name`` label 30 ``any:!apps\.kubernetes\.io/pod-index`` Ignore ``apps.kubernetes.io/pod-index`` label 31 ``any:!batch\.kubernetes\.io/job-completion-index`` Ignore ``batch.kubernetes.io/job-completion-index`` label 32 ``any:!batch\.kubernetes\.io/controller-uid`` Ignore ``batch.kubernetes.io/controller-uid`` label 33 ``any:!beta\.kubernetes\.io`` Ignore all ``beta.kubernetes.io`` labels 34 ``any:!k8s\.io`` Ignore all ``k8s.io`` labels 35 ``any:!pod-template-generation`` Ignore all ``pod-template-generation`` labels 36 ``any:!pod-template-hash`` Ignore all ``pod-template-hash`` labels 37 ``any:!controller-revision-hash`` Ignore all ``controller-revision-hash`` labels 38 ``any:!annotation.*`` Ignore all ``annotation`` labels 39 ``any:!controller-uid`` Ignore all ``controller-uid`` labels 40 ``any:!etcd_node`` Ignore all ``etcd_node`` labels 41 =================================================== ========================================================= 42 43 The above label patterns are all *exclusive label patterns*, that is to say 44 they define which label keys should be ignored. These are identified by the 45 presence of the ``!`` character. 46 47 Label configurations that do not contain the ``!`` character are *inclusive 48 label patterns*. Once at least one inclusive label pattern is added, only 49 labels that match the inclusive label configuration may be considered relevant 50 for identities. Additionally, when at least one inclusive label pattern is 51 configured, the following inclusive label patterns are automatically added to 52 the configuration: 53 54 ========================================== ===================================================== 55 Label Description 56 ------------------------------------------ ----------------------------------------------------- 57 ``reserved:.*`` Include all ``reserved:`` labels 58 ``any:io\.kubernetes\.pod\.namespace`` Include all ``io.kubernetes.pod.namespace`` labels 59 ``any:io\.cilium\.k8s\.namespace\.labels`` Include all ``io.cilium.k8s.namespace.labels`` labels 60 ``any:app\.kubernetes\.io`` Include all ``app.kubernetes.io`` labels 61 ========================================== ===================================================== 62 63 64 65 Configuring Identity-Relevant Labels 66 ------------------------------------ 67 68 To limit the labels used for evaluating Cilium identities, edit the Cilium 69 ConfigMap object using ``kubectl edit cm -n kube-system cilium-config`` and 70 insert a line to define the label patterns to include or exclude. Alternatively, 71 this attribute can also be set via helm option ``--set labels=<values>``. 72 73 .. code-block:: yaml 74 75 apiVersion: v1 76 data: 77 ... 78 kube-proxy-replacement: "true" 79 labels: "k8s:io.kubernetes\\.pod\\.namespace k8s:k8s-app k8s:app k8s:name" 80 enable-ipv4-masquerade: "true" 81 monitor-aggregation: medium 82 ... 83 84 .. note:: The double backslash in ``\\.`` is required to escape the slash in 85 the YAML string so that the regular expression contains ``\.``. 86 87 Label patterns are regular expressions that are implicitly anchored at the 88 start of the label. For example ``example\.com`` will match labels that start 89 with ``example.com``, whereas ``.*example\.com`` will match labels that contain 90 ``example.com`` anywhere. Be sure to escape periods in domain names to avoid 91 the pattern matching too broadly and therefore including or excluding too many 92 labels. 93 94 Upon defining a custom list of label patterns in the ConfigMap, Cilium adds the 95 provided list of label patterns to the default list of label patterns. After 96 saving the ConfigMap, restart the Cilium Agents to pickup the new label pattern 97 setting. 98 99 .. code-block:: shell-session 100 101 kubectl delete pods -n kube-system -l k8s-app=cilium 102 103 .. note:: Configuring Cilium with label patterns via ``labels`` Helm value does 104 **not** override the default set of label patterns. 105 106 Existing identities will not change as a result of this new configuration. To 107 apply the new label pattern setting to existing identities, restart the 108 associated pods. Upon restart, new identities will be created. The old 109 identities will be garbage collected by the Cilium Operator once they are no 110 longer used by any Cilium endpoints. 111 112 When specifying multiple label patterns to evaluate, provide the list of labels 113 as a space-separated string. 114 115 Including Labels 116 ---------------- 117 118 Labels can be defined as a list of labels to include. Only the labels specified 119 and the default inclusive labels will be used to evaluate Cilium identities: 120 121 .. code-block:: yaml 122 123 labels: "k8s:io.kubernetes\\.pod\\.namespace k8s:k8s-app k8s:app k8s:name" 124 125 The above configuration would only include the following label keys when 126 evaluating Cilium identities: 127 128 - k8s:k8s-app 129 - k8s:app 130 - k8s:name 131 - reserved:.* 132 - io\.kubernetes\.pod\.namespace 133 - io\.cilium\.k8s.namespace\.labels 134 - app\.kubernetes\.io 135 136 Note that ``k8s:io\.kubernetes\.pod\.namespace`` is already included in default 137 label ``io\.kubernetes\.pod\.namespace``. 138 139 Labels with the same prefix as defined in the configuration will also be 140 considered. This lists some examples of label keys that would also be evaluated 141 for Cilium identities: 142 143 - k8s-app-team 144 - app-production 145 - name-defined 146 147 When a single inclusive label is added to the filter, all labels not defined 148 in the default list will be excluded. For example, pods running with the 149 security labels ``team=team-1, env=prod`` will have the label ``env=prod`` 150 ignored as soon Cilium is started with the filter ``k8s:team``. 151 152 Excluding Labels 153 ---------------- 154 155 Label patterns can also be specified as a list of exclusions. Exclude labels 156 by placing an exclamation mark after colon separating the prefix and pattern. 157 When defined as a list of exclusions, Cilium will include the set of default 158 labels, but will exclude any matches in the provided list when evaluating 159 Cilium identities: 160 161 .. code-block:: yaml 162 163 labels: "k8s:!controller-uid k8s:!job-name" 164 165 The provided example would cause Cilium to exclude any of the following label 166 matches: 167 168 - k8s:controller-uid 169 - k8s:job-name