freeleaps-ops/cluster/manifests/freeleaps-infra-system/telepresence/telepresence-oss/README.md

Telepresence

Telepresence is a tool that allows for local development of microservices running in a remote Kubernetes cluster.

This chart manages the server-side components of Telepresence so that an operations team can give limited access to the cluster for developers to work on their services.

Install

The telepresence binary embeds the helm chart, so the easiest way to install is:

$ telepresence helm install [--set x=y | --values <values file>]

Configuration

The following tables lists the configurable parameters of the Telepresence chart and their default values.

Parameter	Description	Default
affinity	Define the Node Affinity and Anti-Affinity for the Traffic Manager.	{}
agent.appProtocolStrategy	The strategy to use when determining the application protocol to use for intercepts	http2Probe
agent.image.name	The name of the injected agent image	""
agent.image.pullPolicy	Pull policy in the webhook for the traffic agent image	IfNotPresent
agent.image.tag	The tag for the injected agent image	"" (Defined in appVersion Chart.yaml)
agent.image.registry	The registry for the injected agent image	ghcr.io/telepresenceio
agent.initResources	The resources for the injected init container
agent.logLevel	The logging level for the traffic-agent	defaults to logLevel
agent.mountPolicies	The policies for the agents. Key is either volume name or path prefix starting with '/'	/tmp: Local
agent.resources	The resources for the injected agent container
agent.securityContext	The security context to use for the injected agent container	defaults to the securityContext of the first container of the app
agent.initSecurityContext	The security context to use for the injected init container	`{}
`
agent.initContainer.enabled	Whether to enable/disable injection of the initContainer	true
agentInjector.certificate.accessMethod	Method used by the agent injector to access the certificate (watch or mount).	watch
agentInjector.certificate.certmanager.commonName	The common name of the generated Certmanager certificate.	agent-injector
agentInjector.certificate.certmanager.duration	The certificate validity duration. (optional value)	2160h0m0s
agentInjector.certificate.certmanager.issuerRef.kind	The Issuer kind to use to generate the self signed certificate. (Issuer of ClusterIssuer)	Issuer
agentInjector.certificate.certmanager.issuerRef.name	The Issuer name to use to generate the self signed certificate.	telepresence
agentInjector.certificate.method	Method used when generating the certificate used for mutating webhook (helm, supplied, or certmanager).	helm
agentInjector.certificate.regenerate	Whether the certificate used for the mutating webhook should be regenerated.	false
agentInjector.enabled	Enable/Disable the agent-injector and its webhook.	true
agentInjector.name	Name to use with objects associated with the agent-injector.	agent-injector
agentInjector.injectPolicy	Determines when an agent is injected, possible values are OnDemand and WhenEnabled	OnDemand
agentInjector.secret.name	The name of the secret the agent-injector webhook uses for authorization with the kubernetes api will expose.	mutator-webhook-tls
agentInjector.service.type	Type of service for the agent-injector.	ClusterIP
agentInjector.webhook.admissionReviewVersions:	List of supported admissionReviewVersions.	["v1"]
agentInjector.webhook.failurePolicy:	Action to take on unexpected failure or timeout of webhook.	Ignore
agentInjector.webhook.name	The name of the agent-injector webhook	agent-injector-webhook
agentInjector.webhook.namespaceSelector:	The namespaceSelector used by the agent-injector webhook when the traffic-manager is not namespaced. Deprecated, use top level namespaces or namespaceSelector	{}
agentInjector.webhook.port:	Port for the service that provides the admission webhook	443
agentInjector.webhook.reinvocationPolicy:	Specify if the webhook may be called again after the initial webhook call. Possible values are Never and IfNeeded.	IfNeeded
agentInjector.webhook.servicePath:	Path to the service that provides the admission webhook	/traffic-agent
agentInjector.webhook.sideEffects:	Any side effects the admission webhook makes outside of AdmissionReview.	None
agentInjector.webhook.timeoutSeconds:	Timeout of the admission webhook	5
apiPort	The port used by the Traffic Manager gRPC API	8081
client.connectionTTL	Deprecated: using grpc.connectionTTL	24h
client.dns.excludeSuffixes	Suffixes for which the client DNS resolver will always fail (or fallback in case of the overriding resolver)	[".com", ".io", ".net", ".org", ".ru"]
client.dns.includeSuffixes	Suffixes for which the client DNS resolver will always attempt to do a lookup. Includes have higher priority than excludes.	[]
client.routing.allowConflictingSubnets	Allow the specified subnets to be routed even if they conflict with other routes on the local machine.	[]
client.routing.alsoProxySubnets	The virtual network interface of connected clients will also proxy these subnets	[]
client.routing.neverProxySubnets	The virtual network interface of connected clients never proxy these subnets	[]
clientRbac.create	Create RBAC resources for non-admin users with this release.	false
clientRbac.namespaced	Restrict the users to specific namespaces. Deprecated and no longer used.	false
clientRbac.namespaces	The namespaces to give users access to.	Traffic Manager's namespaces (unless dynamic)
clientRbac.subjects	The user accounts to tie the created roles to.	{}
grpc.connectionTTL	The time that the traffic-manager will retain a client connection without any sign of life from the workstation	24h
grpc.maxReceiveSize	Max size of a gRCP message	4Mi
hooks.busybox.image	The name of the image to use for busybox.	busybox
hooks.busybox.imagePullSecrets	The Secret storing any credentials needed to access the image in a private registry.	[]
hooks.busybox.registry	The registry to download the image from.	docker.io
hooks.busybox.tag	Override the version of busybox to be installed.	latest
hooks.curl.registry	The repository to download the image from.	docker.io
hooks.curl.image	The name of the image to use for curl.	curlimages/curl
hooks.curl.imagePullSecrets	The Secret storing any credentials needed to access the image in a private registry.	[]
hooks.curl.pullPolicy	Pull policy used when pulling the curl image.	IfNotPresent
hooks.curl.tag	Override the version of busybox to be installed.	latest
hooks.podSecurityContext	The Kubernetes SecurityContext for the chart hooks Pod	{}
image.registry	The repository to download the image from. Set TELEPRESENCE_REGISTRY=image.registry locally if changing this value.	ghcr.io/telepresenceio
hooks.resources	Define resource requests and limits for the chart hooks	{}
hooks.securityContext	The Kubernetes SecurityContext for the chart hooks Container	securityContext
image.imagePullSecrets	The Secret storing any credentials needed to access the image in a private registry.	[]
image.name	The name of the image to use for the traffic-manager	tel2
image.pullPolicy	How the Pod will attempt to pull the image.	IfNotPresent
image.tag	Override the version of the Traffic Manager to be installed.	"" (Defined in appVersion Chart.yaml)
livenessProbe	Define livenessProbe for the Traffic Manger.	{}
logLevel	Define the logging level of the Traffic Manager	debug
managerRbac.create	Create RBAC resources for traffic-manager with this release.	true
managerRbac.namespaced	Whether the traffic manager should be restricted to specific namespaces. Deprecated and no longer used.	false
managerRbac.namespaces	Which namespaces the traffic manager should be restricted to. Deprecated, use top level namespaces or namespaceSelector	[]
maxNamespaceSpecificWatchers	Threshold controlling when the traffic-manager switches from using watchers for each managed namespace to using cluster-wide watchers.	10
namespaces	Declares a fixed set of managed namespaces. Mutually exclusive to namespaceSelector	[]
namespaceSelector	Declares the managed namespace using matchLabels and matchExpressions. Mutually exclusive to namespaces	{}
nodeSelector	Define which Nodes you want to the Traffic Manager to be deployed to.	{}
podAnnotations	Annotations for the Traffic Manager Pod	{}
podLabels	Labels for the Traffic Manager Pod	{}
podCIDRs	Verbatim list of CIDRs that the cluster uses for pods. Only valid together with podCIDRStrategy: environment	[]
podCIDRStrategy	Define the strategy that the traffic-manager uses to discover what CIDRs the cluster uses for pods	auto
podSecurityContext	The Kubernetes SecurityContext for the Pod	{}
priorityClassName	Name of the existing priority class to be used	""
rbac.only	Only create the RBAC resources and omit the traffic-manger.	false
readinessProbe	Define readinessProbe for the Traffic Manger.	{}
resources	Define resource requests and limits for the Traffic Manger.	{}
schedulerName	Specify a scheduler for Traffic Manager Pod and hooks Pod.
securityContext	The Kubernetes SecurityContext for the Deployment	{"readOnlyRootFilesystem": true, "runAsNonRoot": true, "runAsUser": 1000}
service.type	The type of Service for the Traffic Manager.	ClusterIP
telepresenceAPI.port	The port on agent's localhost where the Telepresence API server can be found
timeouts.agentArrival	The time that the traffic-manager will wait for the traffic-agent to arrive	30s
tolerations	Define tolerations for the Traffic Manager to ignore Node taints.	[]
workloads.argoRollouts.enabled	Enable/Disable the argo-rollouts integration.	false
workloads.deployments.enabled	Enable/Disable the support for Deployments.	true
workloads.replicaSets.enabled	Enable/Disable the support for ReplicaSets.	true
workloads.statefulSets.enabled	Enable/Disable the support for StatefulSets.	true

RBAC

Telepresence requires a cluster for installation but restricted RBAC roles can be used to give users access to create intercepts if they are not cluster admins.

The chart gives you the ability to create these RBAC roles for your users and give access to the entire cluster or restrict to certain namespaces.

You can also create a separate release for managing RBAC by setting Values.rbac.only: true.

Namespace-scoped traffic manager

Telepresence's Helm chart supports installing a Traffic Manager at the namespace scope. You might want to do this if you have multiple namespaces, say representing multiple different environments, and would like their Traffic Managers to be isolated from one another. To do this, set managerRbac.namespaced=true and managerRbac.namespaces={a,b,c} to manage namespaces a, b and c.

NOTE Do not install namespace-scoped traffic managers and a cluster-scoped traffic manager in the same cluster!

Namespace collision detection

The Telepresence Helm chart will try to prevent namespace-scoped Traffic Managers from managing the same namespaces. It will do this by creating a ConfigMap, called traffic-manager-claim, in each namespace that a given install manages.

So, for example, suppose you install one Traffic Manager to manage namespaces a and b, as:

$ telepresence helm install --namespace a --set 'managerRbac.namespaced=true' --set 'managerRbac.namespaces={a,b}'

You might then attempt to install another Traffic Manager to manage namespaces b and c:

$ telepresence helm install --namespace c --set 'managerRbac.namespaced=true' --set 'managerRbac.namespaces={b,c}'

This would fail with an error:

Error: rendered manifests contain a resource that already exists. Unable to continue with install: ConfigMap "traffic-manager-claim" in namespace "b" exists and cannot be imported into the current release: invalid ownership metadata; annotation validation error: key "meta.helm.sh/release-namespace" must equal "c": current value is "a"

To fix this error, fix the overlap either by removing b from the first install, or from the second.

Pod CIDRs

The traffic manager is responsible for keeping track of what CIDRs the cluster uses for the pods. The Telepresence client uses this information to configure the network so that it provides access to the pods. In some cases, the traffic-manager will not be able to retrieve this information, or will do it in a way that is inefficient. To remedy this, the strategy that the traffic manager uses can be configured using the podCIDRStrategy.

Value	Meaning
auto	First try nodePodCIDRs and if that fails, try coverPodIPs
coverPodIPs	Obtain all IPs from the podIP and podIPs of all Pod resource statuses and calculate the CIDRs needed to cover them.
environment	Pick the CIDRs from the traffic manager's POD_CIDRS environment variable. Use podCIDRs to set that variable.
nodePodCIDRs	Obtain the CIDRs from thepodCIDR and podCIDRs of all Node resource specifications.