<commit_before>[[admin-guide-manage-pods]]
= Managing Pods
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:
:prewrap!:

toc::[]

== Overview

This topic describes the management of
xref:../architecture/core_concepts/pods_and_services.adoc#pods[pods], including
managing their networks, limiting their run-once duration, and limiting what
they can access, and how much bandwidth they can use.

[[admin-guide-pod-network]]
== Managing Pod Networks

ifdef::openshift-dedicated[]
include::admin_guide/osd_request.adoc[]
endif::[]

When your cluster is configured to use
xref:../architecture/additional_concepts/sdn.adoc#architecture-additional-concepts-sdn[the *ovs-multitenant* SDN
plug-in], you can manage the separate pod overlay networks for projects using
the administrator CLI.
ifdef::openshift-enterprise,openshift-origin[]
See the xref:../install_config/configuring_sdn.adoc#install-config-configuring-sdn[Configuring the SDN] section
for plug-in configuration steps, if necessary.
endif::openshift-enterprise,openshift-origin[]

[[joining-project-networks]]
=== Joining Project Networks

To join projects to an existing project network:

----
$ oadm pod-network join-projects --to=<project1> <project2> <project3>
----

In the above example, all the pods and services in `<project2>` and `<project3>`
can now access any pods and services in `<project1>` and vice versa.

Alternatively, instead of specifying specific project names, you can use the
`--selector=<project_selector>` option.

[[isolating-project-networks]]
== Isolating Project Networks

To isolate the project network in the cluster and vice versa, run:

----
$ oadm pod-network isolate-projects <project1> <project2>
----

In the above example, all of the pods and services in `<project1>` and
`<project2>` can _not_ access any pods and services from other non-global
projects in the cluster and vice versa.

Alternatively, instead of specifying specific project names, you can use the
`--selector=<project_selector>` option.

[[making-project-networks-global]]
=== Making Project Networks Global

To allow projects to access all pods and services in the cluster and vice versa:

----
$ oadm pod-network make-projects-global <project1> <project2>
----

In the above example, all the pods and services in `<project1>` and `<project2>`
can now access any pods and services in the cluster and vice versa.

Alternatively, instead of specifying specific project names, you can use the
`--selector=<project_selector>` option.

ifdef::openshift-enterprise,openshift-origin[]
[[manage-pods-limit-run-once-duration]]
== Limiting Run-once Pod Duration

{product-title} relies on run-once pods to perform tasks such as
xref:../dev_guide/deployments.adoc#dev-guide-deployments[deploying a pod] or
xref:../dev_guide/builds.adoc#dev-guide-builds[performing a build]. Run-once pods are pods that
have a `*RestartPolicy*` of `Never` or `OnFailure`.

The cluster administrator can use the *RunOnceDuration* admission control
plug-in to force a limit on the time that those run-once pods can be active.
Once the time limit expires, the cluster will try to actively terminate those
pods. The main reason to have such a limit is to prevent tasks such as builds to
run for an excessive amount of time.

[[configuring-the-run-once-duration-plug-in]]
=== Configuring the RunOnceDuration Plug-in

The plug-in configuration should include the default active deadline for
run-once pods. This deadline will be enforced globally, but can be superseded on
a per-project basis.

====

[source,yaml]
----
kubernetesMasterConfig:
  admissionConfig:
    pluginConfig:
      RunOnceDuration:
        configuration:
          apiVersion: v1
          kind: RunOnceDurationConfig
          activeDeadlineSecondsOverride: 3600 <1>
----

<1> Specify the global default for run-once pods in seconds.

====

[[specifying-a-custom-duration-per-project]]
=== Specifying a Custom Duration per Project

In addition to specifying a global maximum duration for run-once pods, an
administrator can add an annotation
(`openshift.io/active-deadline-seconds-override`) to a specific project to
override the global default.

====

[source,yaml]
----
apiVersion: v1
kind: Project
metadata:
  annotations:
    openshift.io/active-deadline-seconds-override: "1000" <1>
----

<1> Overrides the default active deadline seconds for run-once pods to 1000 seconds.
Note that the value of the override must be specified in string form.

====
endif::openshift-enterprise,openshift-origin[]

[[admin-guide-limit-pod-access-egress]]
== Limiting Pod Access with Egress Firewall

As an {product-title} cluster administrator, you can use egress policy to limit
the addresses that some or all pods can access from within the cluster, so that:

- A pod can only talk to internal hosts, and cannot initiate connections to the
public Internet.
+
Or,
- A pod can only talk to the public Internet, and cannot initiate connections to
internal hosts (outside the cluster).
+
Or,
- A pod cannot reach specified internal subnets/hosts that it should have no
reason to contact.

For example, you can configure projects with different egress policies, allowing
`<project A>` access to a specified IP range, but denying the same access to
`<project B>`.

[CAUTION]
====
You must have the
xref:../install_config/configuring_sdn.adoc#install-config-configuring-sdn[*ovs-multitenant* plug-in] enabled in order to limit pod access via egress policy.
====

Project administrators can neither create `*EgressNetworkPolicy*` objects, nor
edit the ones you create in their project.

The `default` project (and any other global namespace) cannot have egress
policy.

[NOTE]
====
If you merge two projects together (via `oadm pod-network join-projects`),
then you cannot use egress policy in _any_ of the joined projects.

If you make a project global (via `oadm pod-network make-projects-global`),
then it cannot have an `*EgressNetworkPolicy*`.

If an allowed network overlaps with a denied network, then the rules are
checked in order, and the first one that matches is enforced.
====

[[admin-guide-config-pod-access]]
=== Configuring Pod Access Limits

To configure pod access limits, you must use the `oc` command or the REST API.
You can use `oc [create|replace|delete]` to manipulate `*EgressNetworkPolicy*`
objects. The *_api/swagger-spec/oapi-v1.json_* file has API-level details on how
the objects actually work.

To configure pod access limits:

. Navigate to the project you want to affect.
. Create a JSON file for the pod limit policy:<commit_msg>Add OpenShift Egress Router content<commit_after>[[admin-guide-manage-pods]]
= Managing Pods
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:
:prewrap!:

toc::[]

== Overview

This topic describes the management of
xref:../architecture/core_concepts/pods_and_services.adoc#pods[pods], including
managing their networks, limiting their run-once duration, and limiting what
they can access, and how much bandwidth they can use.

[[admin-guide-pod-network]]
== Managing Pod Networks

ifdef::openshift-dedicated[]
include::admin_guide/osd_request.adoc[]
endif::[]

When your cluster is configured to use
xref:../architecture/additional_concepts/sdn.adoc#architecture-additional-concepts-sdn[the *ovs-multitenant* SDN
plug-in], you can manage the separate pod overlay networks for projects using
the administrator CLI.
ifdef::openshift-enterprise,openshift-origin[]
See the xref:../install_config/configuring_sdn.adoc#install-config-configuring-sdn[Configuring the SDN] section
for plug-in configuration steps, if necessary.
endif::openshift-enterprise,openshift-origin[]

[[joining-project-networks]]
=== Joining Project Networks

To join projects to an existing project network:

----
$ oadm pod-network join-projects --to=<project1> <project2> <project3>
----

In the above example, all the pods and services in `<project2>` and `<project3>`
can now access any pods and services in `<project1>` and vice versa.

Alternatively, instead of specifying specific project names, you can use the
`--selector=<project_selector>` option.

[[isolating-project-networks]]
== Isolating Project Networks

To isolate the project network in the cluster and vice versa, run:

----
$ oadm pod-network isolate-projects <project1> <project2>
----

In the above example, all of the pods and services in `<project1>` and
`<project2>` can _not_ access any pods and services from other non-global
projects in the cluster and vice versa.

Alternatively, instead of specifying specific project names, you can use the
`--selector=<project_selector>` option.

[[making-project-networks-global]]
=== Making Project Networks Global

To allow projects to access all pods and services in the cluster and vice versa:

----
$ oadm pod-network make-projects-global <project1> <project2>
----

In the above example, all the pods and services in `<project1>` and `<project2>`
can now access any pods and services in the cluster and vice versa.

Alternatively, instead of specifying specific project names, you can use the
`--selector=<project_selector>` option.

ifdef::openshift-enterprise,openshift-origin[]
[[manage-pods-limit-run-once-duration]]
== Limiting Run-once Pod Duration

{product-title} relies on run-once pods to perform tasks such as
xref:../dev_guide/deployments.adoc#dev-guide-deployments[deploying a pod] or
xref:../dev_guide/builds.adoc#dev-guide-builds[performing a build]. Run-once pods are pods that
have a `*RestartPolicy*` of `Never` or `OnFailure`.

The cluster administrator can use the *RunOnceDuration* admission control
plug-in to force a limit on the time that those run-once pods can be active.
Once the time limit expires, the cluster will try to actively terminate those
pods. The main reason to have such a limit is to prevent tasks such as builds to
run for an excessive amount of time.

[[configuring-the-run-once-duration-plug-in]]
=== Configuring the RunOnceDuration Plug-in

The plug-in configuration should include the default active deadline for
run-once pods. This deadline is enforced globally, but can be superseded on
a per-project basis.

====

[source,yaml]
----
kubernetesMasterConfig:
  admissionConfig:
    pluginConfig:
      RunOnceDuration:
        configuration:
          apiVersion: v1
          kind: RunOnceDurationConfig
          activeDeadlineSecondsOverride: 3600 <1>
----

<1> Specify the global default for run-once pods in seconds.

====

[[specifying-a-custom-duration-per-project]]
=== Specifying a Custom Duration per Project

In addition to specifying a global maximum duration for run-once pods, an
administrator can add an annotation
(`openshift.io/active-deadline-seconds-override`) to a specific project to
override the global default.

====

[source,yaml]
----
apiVersion: v1
kind: Project
metadata:
  annotations:
    openshift.io/active-deadline-seconds-override: "1000" <1>
----

<1> Overrides the default active deadline seconds for run-once pods to 1000 seconds.
Note that the value of the override must be specified in string form.

====
endif::openshift-enterprise,openshift-origin[]

[[admin-guide-controlling-egress-traffic]]
== Controlling Egress Traffic
As an {product-title} cluster administrator, you can control egress traffic
using either a xref:admin-guide-deploying-an-egress-router-service[router] or
xref:admin-guide-limit-pod-access-egress[firewall] methods.

[[admin-guide-limit-pod-access-egress-router]]
=== Limiting Pod Access with an Egress Router

The {product-title} egress router runs a service that redirects traffic to a
specified remote server, using a private source IP address that is not used for
anything else. The service allow pods to talk to servers that are set up
to only allow access from whitelisted IP addresses.

[[admin-guide-deploying-an-egress-router-pod]]
==== Deploying an Egress Router Pod

.Example Pod Definition for an Egress Router
====
----
apiVersion: v1
kind: Pod
metadata:
  name: egress-1
  labels:
    name: egress-1
  annotations:
    pod.network.openshift.io/assign-macvlan: true
spec:
  containers:
  - name: egress-router
    image: openshift/origin-egress-router
    securityContext:
      privileged: true
    env:
    - name: EGRESS_SOURCE <1>
      value: 192.168.12.99
    - name: EGRESS_GATEWAY <2>
      value: 192.168.12.1
    - name: EGRESS_DESTINATION <3>
      value: 203.0.113.25
  nodeSelector:
    site: springfield-1 <4>
----
<1> IP address on the node subnet reserved by the cluster administrator for use by
this pod.
<2> Same value as the default gateway used by the node itself.
<3>  Connections to the pod are redirected to 203.0.113.25, with a source IP
address of 192.168.12.99
<4> The pod will only be deployed to nodes with the label site *springfield-1*.
====

The `pod.network.openshift.io/assign-macvlan annotation` creates a Macvlan
network interface on the primary network interface, and then moves it into the
pod's network name space before starting the *egress-router* container.

The pod contains a single container, using the *openshift/origin-egress-router*
image, and that container is run privileged so that it can configure the Macvlan
interface and set up `iptables` rules.

The environment variables tell the *egress-router* image what addresses to use; it
will configure the Macvlan interface to use `*EGRESS_SOURCE*` as its IP address,
with `*EGRESS_GATEWAY*` as its gateway.

NAT rules are set up so that connections to any TCP or UDP port on the
pod's cluster IP address are redirected to the same port on
`*EGRESS_DESTINATION*`.

If only some of the nodes in your cluster are capable of claiming the specified
source IP address and using the specified gateway, you can specify a
`*nodeName*` or `*nodeSelector*` indicating which nodes are acceptable.

[[admin-guide-deploying-an-egress-router-service]]
==== Deploying an Egress Router Service

Though not strictly necessary, you normally want to create a service pointing to
the egress router:

====
----
apiVersion: v1
kind: Service
metadata:
  name: egress-1
spec:
  ports:
  - name: http
    port: 80
  - name: https
    port: 443
  type: ClusterIP
  selector:
    name: egress-1
----
====

Your pods can now connect to this service. Their connections are redirected to
the corresponding ports on the external server, using the reserved egress IP
address.

[[admin-guide-limit-pod-access-egress]]
=== Limiting Pod Access with Egress Firewall

As an {product-title} cluster administrator, you can use egress policy to limit
the addresses that some or all pods can access from within the cluster, so that:

- A pod can only talk to internal hosts, and cannot initiate connections to the
public Internet.
+
Or,
- A pod can only talk to the public Internet, and cannot initiate connections to
internal hosts (outside the cluster).
+
Or,
- A pod cannot reach specified internal subnets/hosts that it should have no
reason to contact.

For example, you can configure projects with different egress policies, allowing
`<project A>` access to a specified IP range, but denying the same access to
`<project B>`.

[CAUTION]
====
You must have the
xref:../install_config/configuring_sdn.adoc#install-config-configuring-sdn[*ovs-multitenant* plug-in] enabled in order to limit pod access via egress policy.
====

Project administrators can neither create `*EgressNetworkPolicy*` objects, nor
edit the ones you create in their project.

The `default` project (and any other global namespace) cannot have egress
policy.

[NOTE]
====
If you merge two projects together (via `oadm pod-network join-projects`),
then you cannot use egress policy in _any_ of the joined projects.

If you make a project global (via `oadm pod-network make-projects-global`),
then it cannot have an `*EgressNetworkPolicy*`.

If an allowed network overlaps with a denied network, then the rules are
checked in order, and the first one that matches is enforced.
====

[[admin-guide-config-pod-access]]
==== Configuring Pod Access Limits

To configure pod access limits, you must use the `oc` command or the REST API.
You can use `oc [create|replace|delete]` to manipulate `*EgressNetworkPolicy*`
objects. The *_api/swagger-spec/oapi-v1.json_* file has API-level details on how
the objects actually work.

To configure pod access limits:

. Navigate to the project you want to affect.
. Create a JSON file for the pod limit policy:
{'fraction_non_alphanumeric': 0.09111395334673245, 'fraction_numerical': 0.008161276569827638, 'mean_word_length': 4.532345013477089, 'pattern_counts': {'":': 0, '<': 57, '<?xml version=': 0, '>': 57, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 5, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3804595', 'n_tokens_mistral': 4946, 'n_tokens_neox': 4602, 'n_words': 1980}