Skip to content

[EV-6714] Recommend kubernetes.io/metadata.name for namespaceSelector #3036

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ti-afra wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[EV-6714] Recommend kubernetes.io/metadata.name for namespaceSelector #3036

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 11 additions & 10 deletions calico-cloud/network-policy/beginners/calico-labels.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ description: Reference list of automatic labels Calico Cloud attaches to resourc

# Calico Cloud automatic labels

As a convenience, $[prodname] provides immutable labels that are used for specific resources when evaluating selectors in policies. The labels make it easier to match resources in common ways (such as matching a namespace by name).
As a convenience, $[prodname] provides immutable labels that are used for specific resources when evaluating selectors in policies, and works with the labels Kubernetes applies automatically. The labels make it easier to match resources in common ways (such as matching a namespace by name).

## Labels for matching namespaces

The label `projectcalico.org/name` is set to the name of the namespace. This allows for matching namespaces by name when using a `namespaceSelector` field.
Kubernetes sets the label `kubernetes.io/metadata.name` to the name of the namespace. This allows for matching namespaces by name when using a `namespaceSelector` field.

For example, the following GlobalNetworkPolicy applies to workloads with label, `color: red` in namespaces named, `"foo"` and `"bar"`. The policy allows ingress traffic to port 8080 from all workloads in a third namespace named, `"baz"`:

Expand All @@ -18,14 +18,14 @@ kind: GlobalNetworkPolicy
metadata:
name: foo-and-bar
spec:
namespaceSelector: projectcalico.org/name in {"foo", "bar"}
namespaceSelector: kubernetes.io/metadata.name in {"foo", "bar"}
selector: color == "red"
types:
- Ingress
ingress:
- action: Allow
source:
namespaceSelector: projectcalico.org/name == "baz"
namespaceSelector: kubernetes.io/metadata.name == "baz"
destination:
ports:
- 8080
Expand All @@ -52,7 +52,7 @@ means "resources in any namespace and non-namespaced resources that match foo ==
Further,

```yaml
namespaceSelector: projectcalico.org/name == "some-namespace"
namespaceSelector: kubernetes.io/metadata.name == "some-namespace"
selector: foo == "bar"
```
is equivalent to:
Expand All @@ -64,11 +64,11 @@ is equivalent to:

### Labels for matching service accounts

Similarly, the `projectcalico.org/name` label is applied to ServiceAccounts and allows for matching by name in a `serviceAccountSelector`.
The `projectcalico.org/name` label is applied to ServiceAccounts and allows for matching by name in a `serviceAccountSelector`. Kubernetes has no equivalent automatic label for ServiceAccounts, so use `projectcalico.org/name` here.

### Kubernetes labels for matching namespaces
### The projectcalico.org/name label for namespaces {/* #projectcalico-name-label-for-namespaces */}

Kubernetes also has [automatic labeling](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/#automatic-labelling), for example `kubernetes.io/metadata.name`. The Kubernetes namespace label serves the same purpose and can be used in the same way as the $[prodname] label. The `projectcalico.org/name` label predates the automatic Kubernetes label.
$[prodname] also sets `projectcalico.org/name` to the name of the namespace, and it can be used in a `namespaceSelector` in the same way. It predates the Kubernetes [automatic labeling](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/#automatic-labelling), and $[prodname] derives it as it reads the namespace rather than storing it on the object, so `kubectl get namespace --show-labels` does not show it. For matching namespaces, prefer `kubernetes.io/metadata.name`.
Comment thread
ti-afra marked this conversation as resolved.

## Labels for matching host endpoints

Expand All @@ -80,7 +80,8 @@ Kubernetes also has [automatic labeling](https://kubernetes.io/docs/concepts/ove

$[prodname] labels must be used with the correct selector or the policy will not work as designed (and there are no error messages in the web console or when applying the YAML).

| Calico label | Usage requirements | Use in these resources... |
| Label | Usage requirements | Use in these resources... |
| --------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| `projectcalico.org/name` | Use with a **namespaceSelector** or **serviceAccountSelector**. | - Network policy<br />- Staged network policy<br /><br />Namespaced resources that apply only to workload endpoint resources in the namespace.<br /> |
| `kubernetes.io/metadata.name` | Use with a **namespaceSelector**. | - Network policy<br />- Staged network policy<br /><br />Namespaced resources that apply only to workload endpoint resources in the namespace.<br /> |
| `projectcalico.org/name` | Use with a **serviceAccountSelector**, or with a **namespaceSelector** (prefer `kubernetes.io/metadata.name` for namespaces). | - Network policy<br />- Staged network policy<br /><br />Namespaced resources that apply only to workload endpoint resources in the namespace.<br /> |
| `projectcalico.org/namespace` | Use only with selectors. <br /><br />Use the label as the label name, and a namespace name as the value to compare against (for example projectcalico.org/namespace == "default"). | - Global network policy<br />- Staged global network policy<br /><br />Cluster-wide (non-namespaced) resources that apply to workload endpoint resources in all namespaces, and to host endpoint resources. |
4 changes: 2 additions & 2 deletions calico-cloud/network-policy/policy-best-practices.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ The following policy is a global network policy for a microservice that limits a
15 - action: Allow
16 protocol: TCP
17 source:
18 namespaceSelector: projectcalico.org/name == "sso"
18 namespaceSelector: kubernetes.io/metadata.name == "sso"
19 ports:
20 - '443'
21 - '80'
Expand Down Expand Up @@ -187,7 +187,7 @@ The following policy is a global network policy for a microservice that limits a
59 - action: Allow
60 protocol: TCP
61 source:
62 namespaceSelector: projectcalico.org/name == "warehouse"
62 namespaceSelector: kubernetes.io/metadata.name == "warehouse"
63 destination:
64 ports:
65 - '1433'
Expand Down
4 changes: 2 additions & 2 deletions calico-cloud/networking/egress/egress-gateway-aws.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -851,7 +851,7 @@ By default, that selector can only match egress gateways in the same namespace.
in a different namespace, specify a `namespaceSelector` annotation as well, like this:

```bash
kubectl annotate ns <namespace> egress.projectcalico.org/namespaceSelector="projectcalico.org/name == 'default'"
kubectl annotate ns <namespace> egress.projectcalico.org/namespaceSelector="kubernetes.io/metadata.name == 'default'"
```

Egress gateway annotations have the same [syntax and range of expressions](../../reference/resources/networkpolicy.mdx#selector) as the selector fields in
Expand All @@ -867,7 +867,7 @@ kind: Pod
metadata:
annotations:
egress.projectcalico.org/selector: egress-code == 'red'
egress.projectcalico.org/namespaceSelector: projectcalico.org/name == 'default'
egress.projectcalico.org/namespaceSelector: kubernetes.io/metadata.name == 'default'
Comment thread
ti-afra marked this conversation as resolved.
name: my-client,
namespace: my-namespace,
spec:
Expand Down
4 changes: 2 additions & 2 deletions calico-cloud/networking/egress/egress-gateway-azure.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -503,7 +503,7 @@ By default, that selector can only match egress gateways in the same namespace.
in a different namespace, specify a `namespaceSelector` annotation as well, like this:

```bash
kubectl annotate ns <namespace> egress.projectcalico.org/namespaceSelector="projectcalico.org/name == 'default'"
kubectl annotate ns <namespace> egress.projectcalico.org/namespaceSelector="kubernetes.io/metadata.name == 'default'"
```

Egress gateway annotations have the same [syntax and range of expressions](../../reference/resources/networkpolicy.mdx#selector) as the selector fields in
Expand All @@ -519,7 +519,7 @@ kind: Pod
metadata:
annotations:
egress.projectcalico.org/selector: egress-code == 'red'
egress.projectcalico.org/namespaceSelector: projectcalico.org/name == 'default'
egress.projectcalico.org/namespaceSelector: kubernetes.io/metadata.name == 'default'
Comment thread
ti-afra marked this conversation as resolved.
name: my-client,
namespace: my-namespace,
spec:
Expand Down
4 changes: 2 additions & 2 deletions calico-cloud/networking/egress/egress-gateway-maintenance.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ kind: Pod
metadata:
annotations:
egress.projectcalico.org/selector: egress-code == 'red'
egress.projectcalico.org/namespaceSelector: projectcalico.org/name == 'default'
egress.projectcalico.org/namespaceSelector: kubernetes.io/metadata.name == 'default'
name: poll-my-own-annotations
namespace: default
spec:
Expand Down Expand Up @@ -196,7 +196,7 @@ spec:
app: annotation-aware-workload
annotations:
egress.projectcalico.org/selector: egress-code == 'red'
egress.projectcalico.org/namespaceSelector: projectcalico.org/name == 'default'
egress.projectcalico.org/namespaceSelector: kubernetes.io/metadata.name == 'default'
spec:
containers:
- name: application-container
Expand Down
4 changes: 2 additions & 2 deletions calico-cloud/networking/egress/egress-gateway-on-prem.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -390,7 +390,7 @@ By default, that selector can only match egress gateways in the same namespace.
in a different namespace, specify a `namespaceSelector` annotation as well, like this:

```bash
kubectl annotate ns <namespace> egress.projectcalico.org/namespaceSelector="projectcalico.org/name == 'default'"
kubectl annotate ns <namespace> egress.projectcalico.org/namespaceSelector="kubernetes.io/metadata.name == 'default'"
```

Egress gateway annotations have the same [syntax and range of expressions](../../reference/resources/networkpolicy.mdx#selector) as the selector fields in
Expand All @@ -406,7 +406,7 @@ kind: Pod
metadata:
annotations:
egress.projectcalico.org/selector: egress-code == 'red'
egress.projectcalico.org/namespaceSelector: projectcalico.org/name == 'default'
egress.projectcalico.org/namespaceSelector: kubernetes.io/metadata.name == 'default'
Comment thread
ti-afra marked this conversation as resolved.
name: my-client,
namespace: my-namespace,
spec:
Expand Down
4 changes: 2 additions & 2 deletions calico-cloud/networking/egress/troubleshoot.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,12 +169,12 @@ spec:
cidr: 11.0.0.0/8
description: "Gateway to on prem"
gateway:
namespaceSelector: "projectcalico.org/name == 'default'"
namespaceSelector: "kubernetes.io/metadata.name == 'default'"
selector: "egress-code == 'blue'"
maxNextHops: 2
- description: "Gateway to internet"
gateway:
namespaceSelector: "projectcalico.org/name == 'default'"
namespaceSelector: "kubernetes.io/metadata.name == 'default'"
selector: "egress-code == 'red'"
```

Expand Down
2 changes: 1 addition & 1 deletion calico-enterprise/_includes/content/_entityrule.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ for the rule as a whole to match a packet.
| notNets | Negative match on CIDRs. Match packets with IP not in any of the listed CIDRs. | List of valid IPv4 CIDRs or list of valid IPv6 CIDRs (IPv4 and IPv6 CIDRs shouldn't be mixed in one rule) | list of cidrs |
| selector | Positive match on selected endpoints. If a `namespaceSelector` is also defined, the set of endpoints this applies to is limited to the endpoints in the selected namespaces. | Valid selector | [selector](#selector) | |
| notSelector | Negative match on selected endpoints. If a `namespaceSelector` is also defined, the set of endpoints this applies to is limited to the endpoints in the selected namespaces. | Valid selector | [selector](#selector) | |
| namespaceSelector | Positive match on selected namespaces. If specified, only workload endpoints in the selected Kubernetes namespaces are matched. Matches namespaces based on the labels that have been applied to the namespaces. Defines the scope that selectors will apply to, if not defined then selectors apply to the NetworkPolicy's namespace. Match a specific namespace by name using the `projectcalico.org/name` label. Select the non-namespaced resources like GlobalNetworkSet(s), host endpoints to which this policy applies by using `global()` selector. | Valid selector | [selector](#selector) | |
| namespaceSelector | Positive match on selected namespaces. If specified, only workload endpoints in the selected Kubernetes namespaces are matched. Matches namespaces based on the labels that have been applied to the namespaces. Defines the scope that selectors will apply to, if not defined then selectors apply to the NetworkPolicy's namespace. Match a specific namespace by name using the `kubernetes.io/metadata.name` label. Select the non-namespaced resources like GlobalNetworkSet(s), host endpoints to which this policy applies by using `global()` selector. | Valid selector | [selector](#selector) | |
| ports | Positive match on the specified ports | | list of [ports](#ports) | |
| domains | Positive match on [domain names](#exact-and-wildcard-domain-names). | List of [exact or wildcard domain names](#exact-and-wildcard-domain-names) | list of strings |
| notPorts | Negative match on the specified ports | | list of [ports](#ports) | |
Expand Down
Loading
Loading