This is an automated email from the ASF dual-hosted git repository. astefanutti pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/camel-k.git
commit 4e15b691d47ed8c2aff86c4a08eb0b783f50d636 Author: Antonin Stefanutti <[email protected]> AuthorDate: Wed Jan 12 11:33:37 2022 +0100 feat: Add HTTP proxy documentation --- docs/modules/ROOT/nav.adoc | 1 + .../ROOT/pages/configuration/http-proxy.adoc | 116 +++++++++++++++++++++ docs/modules/ROOT/pages/configuration/maven.adoc | 44 ++++++-- 3 files changed, 153 insertions(+), 8 deletions(-) diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 890e733..068bf24 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -32,6 +32,7 @@ ** xref:configuration/runtime-properties.adoc[Properties] ** xref:configuration/runtime-config.adoc[Runtime configuration] ** xref:configuration/runtime-resources.adoc[Runtime resources] +** xref:configuration/http-proxy.adoc[HTTP Proxy] ** xref:configuration/maven.adoc[Maven] * Observability ** xref:observability/logging.adoc[Logging] diff --git a/docs/modules/ROOT/pages/configuration/http-proxy.adoc b/docs/modules/ROOT/pages/configuration/http-proxy.adoc new file mode 100644 index 0000000..1240c03 --- /dev/null +++ b/docs/modules/ROOT/pages/configuration/http-proxy.adoc @@ -0,0 +1,116 @@ +[[http-proxy]] += HTTP Proxy + +Production or corporate environments can deny direct access to the Internet, and mandates egress traffic to go through an HTTP or HTTPS proxy. + +The Camel K operator can be configured to route egress traffic to this proxy, by setting the usual `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` on the operator Deployment. + +This can be achieved with the Kamel CLI, at installation time, e.g.: + +[source,console] +---- +$ kamel install --operator-env-vars=HTTP_PROXY=http://proxy +---- + +Alternatively, the operator Deployment can be amended with the `kubectl` CLI, e.g.: + +[source,console] +---- +$ kubectl set env deployment camel-k-operator HTTP_PROXY=http://proxy +---- + +The `HTTP_PROXY` and `HTTPS_PROXY` environment variable values expect URLs following the `http://[<username>[:<pswd>]@]<host>[:<port>]` format, e.g.: + +[source] +---- +HTTP_PROXY=http://proxy.corp.tld +---- + +NOTE: Maven currently does not support connecting to an HTTP proxy via TLS. For this reason, the scheme of the `HTTPS_PROXY` value is restricted to `http`. + +The `NO_PROXY` environment variable value expects a comma-separated list of destination domain names, domain suffixes, IP addresses or other network CIDRs, e.g.: + +[source] +---- +NO_PROXY=.cluster.local,.svc,10.0.0.0/16,127.0.0.1,localhost +---- + +By default, all egress traffic, generated by all the workloads and processes managed by the Camel K operator, will be proxied. +This encompasses: + +* Communicating with the Kubernetes API server +* Downloading Maven artifacts from repositories +* Pulling base images from container registries +* Pushing images to the configured container registry + +For this reason, services that the operator requires access to should be reviewed, and it must be determined whether any of them must bypass the proxy. + +This particularly applies to internal services, hosted within the cluster, whose internal domain names or IP addresses should be added to the `NO_PROXY` environment variable. + +Typically, the `NO_PROXY` variable should be populated with the internal domain suffixes, as well as the cluster network CIDRs, e.g.: + +[source] +---- +NO_PROXY=.cluster.local,.svc,10.0.0.0/16,127.0.0.1,172.17.0.0/18,172.21.0.0/16,localhost +---- + +NOTE: As the Camel K operator communicates with the Kubernetes API, the cluster IPs of the Kubernetes Service must at least be specified in `NO_PROXY`, anytime an HTTP proxy is configured. + +By default, the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables are also propagated to the integrations. +This behavior can be deactivated, by using the `http-proxy` parameter of the _environment_ trait, e.g.: + +[source,console] +---- +$ kamel run -t environment.http-proxy=false +---- + +Alternatively, it can be disabled globally, by editing the IntegrationPlatform resources, e.g.: + +[source, yaml] +---- +apiVersion: camel.apache.org/v1 +kind: IntegrationPlatform +metadata: + name: camel-k +spec: + traits: + environment: + configuration: + httpProxy: false # <1> +---- +<1> Deactivates the propagation of HTTP proxy environment variables at the platform level + +[[openshift]] +=== OpenShift + +On OpenShift 4, cluster-wide egress proxy can be configured by editing the `cluster` Proxy resource: + +[source,yaml] +---- +apiVersion: config.openshift.io/v1 +kind: Proxy +metadata: + name: cluster +spec: + httpProxy: http://<username>:<pswd>@<ip>:<port> +---- + +Operator Lifecycle Manager (OLM), sources the status of this `cluster` Proxy, to automatically populate the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables, on the operator Deployment resources it manages. + +These cluster-wide proxy settings can be overwritten, specifically for the Camel K operator if necessary, by editing the corresponding Subscription resource, e.g.: + +[source,yaml] +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: Subscription +metadata: + name: camel-k + namespace: openshift-operators +spec: + config: + env: + - name: HTTP_PROXY + value: "" + - name: NO_PROXY + value: "" +---- diff --git a/docs/modules/ROOT/pages/configuration/maven.adoc b/docs/modules/ROOT/pages/configuration/maven.adoc index d5ff11f..69a7196 100644 --- a/docs/modules/ROOT/pages/configuration/maven.adoc +++ b/docs/modules/ROOT/pages/configuration/maven.adoc @@ -1,5 +1,6 @@ = Configure Maven +[[maven-settings]] == Maven Settings The Maven settings, used by the Camel K operator, can be provided in a ConfigMap or a Secret. @@ -114,6 +115,17 @@ WARNING: The `--maven-settings` and `--maven-repository` options are mutually ex You can find more information in the https://maven.apache.org/guides/introduction/introduction-to-repositories.html[Introduction to Repositories] from the Maven documentation. +[[http-proxy]] +== HTTP Proxy + +HTTP proxy can be configured on the Camel K operator Deployment, with the usual `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables. + +The operator automatically configures Maven according to the values of these variables. + +See the xref:configuration/http-proxy.adoc[HTTP proxy] documentation for more details. + +The generated configuration can be overwritten in the <<maven-settings>> if necessary. + [[ca-certificates]] == CA Certificates @@ -131,6 +143,7 @@ A JKS formatted keystore is automatically created to store the CA certificate(s) The root CA certificates are also imported into the created keystore. The created Secret can then be referenced in the IntegrationPlatform resource, from the `spec.build.maven.caSecret` field, e.g.: + [source,yaml] ---- apiVersion: camel.apache.org/v1 @@ -191,12 +204,18 @@ Maven extensions are typically used to enable https://maven.apache.org/wagon/wag [[use-case]] == S3 Bucket as a Maven Repository -In this section, we will show how to configure Camel K to fetch artifacts from a https://aws.amazon.com/s3/[S3] bucket that's setup as a Maven repository. We will assume that the bucket is already up and running and configured correctly. We will also assume you know how to setup Maven locally to fetch artifacts from it. +In this section, we will show how to configure Camel K to fetch artifacts from a https://aws.amazon.com/s3/[S3] bucket that's set up as a Maven repository. +We will assume that the bucket is already up and running and configured correctly. We will also assume you know how to set up Maven locally to fetch artifacts from it. === Custom Maven Settings -The first thing that needs to be done is to create a Maven settings file configured to use the S3 bucket as a Maven repository. The Maven settings file will be used by the Camel K operator so make sure your S3 instance is accessible in your cluster. + -The Maven settings will contain all the information needed for Maven to access the S3 bucket namely your credentials, S3 URL and bucket name. This information will typically be located in the `server` and `repository` section of your Maven settings. For example when using https://min.io/[MinIO] as a S3 provider and https://github.com/Yleisradio/aws-maven/pull/20[`fi.yle.tools:aws-maven:1.4.3`] as a Wagon Provider, your Maven settings will look something like this: +The first thing that needs to be done is to create a Maven settings file configured to use the S3 bucket as a Maven repository. +The Maven settings file will be used by the Camel K operator so make sure your S3 instance is accessible in your cluster. + +The Maven settings will contain all the information needed for Maven to access the S3 bucket namely your credentials, S3 URL and bucket name. +This information will typically be located in the `server` and `repository` section of your Maven settings. + +For example when using https://min.io/[MinIO] as a S3 provider and https://github.com/Yleisradio/aws-maven/pull/20[`fi.yle.tools:aws-maven:1.4.3`] as a Wagon Provider, your Maven settings will look something like this: [source,xml] ---- @@ -289,7 +308,10 @@ xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache. </profiles> </settings> ---- -Since these settings contains credentials, you will want to store it in a Kubernetes `secret`. As mentioned above, the `kubectl` CLI provides a convenient command to create a Secret from a file, e.g.: + +Since these settings contains credentials, you will want to store it in a Kubernetes Secret. +As mentioned above, the `kubectl` CLI provides a convenient command to create a Secret from a file, e.g.: + [source,console] ---- $ kubectl create secret generic camel-k-s3-maven-settings --from-file=maven-settings=maven_settings.xml @@ -297,8 +319,10 @@ $ kubectl create secret generic camel-k-s3-maven-settings --from-file=maven-sett === S3 TLS Certificates -In most cases, you will need to add the certificate(s) served by your S3 instance to the list of certificate(s) trusted by the Camel K Operator when running Maven commands. Where/how to get the certificate(s) varies greatly depending on how your S3 instance is setup and will not be covered here. + -Once retrieved, you should create a Kubernetes `secret` containing the certificate(s) similar to what is described in the section <<ca-certificates>>, e.g.: +In most cases, you will need to add the certificate(s) served by your S3 instance to the list of certificate(s) trusted by the Camel K Operator when running Maven commands. +Where/how to get the certificate(s) varies greatly depending on how your S3 instance is set up, and will not be covered here. +Once retrieved, you should create a Kubernetes Secret containing the certificate(s) similar to what is described in the section <<ca-certificates>>, e.g.: + [source,console] ---- $ kubectl create secret generic s3-ca --from-file=s3-ca=ca.crt @@ -306,13 +330,17 @@ $ kubectl create secret generic s3-ca --from-file=s3-ca=ca.crt === Maven settings, certificates and extensions -We are now ready to configure the Camel K operator to use your S3 bucket as a Maven repository. This can be done while installing the Operator using the Kamel CLI, e.g: +We are now ready to configure the Camel K operator to use your S3 bucket as a Maven repository. +This can be done while installing the Operator using the Kamel CLI, e.g: + [source,console] ---- $ kamel install --maven-settings secret:camel-k-s3-maven-settings/maven-settings --maven-ca-secret s3-ca/s3-ca --maven-extension fi.yle.tools:aws-maven:1.4.3 ---- -Maven dependencies hosted in your S3 bucket can now be used just like any other dependency when running an integration. For example when using the Kamel CLI using the `--dependency` option: +Maven dependencies hosted in your S3 bucket can now be used just like any other dependency when running an integration. +For example when using the Kamel CLI using the `--dependency` option: + [source,console] ---- $ kamel run S3.java --dependency=mvn:artfiactId:groupId:version
