From 0fbef52cbfc7bcb63e3bd4a533ffb7f2ea44288d Mon Sep 17 00:00:00 2001 From: Marina B Date: Mon, 25 Nov 2024 23:17:27 -0800 Subject: [PATCH 1/2] Fix broken link --- .../modules/ROOT/pages/flex-view-logs-in-runtime-manager.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gateway/1.9/modules/ROOT/pages/flex-view-logs-in-runtime-manager.adoc b/gateway/1.9/modules/ROOT/pages/flex-view-logs-in-runtime-manager.adoc index 5d953a2a4..b9c247524 100644 --- a/gateway/1.9/modules/ROOT/pages/flex-view-logs-in-runtime-manager.adoc +++ b/gateway/1.9/modules/ROOT/pages/flex-view-logs-in-runtime-manager.adoc @@ -17,7 +17,7 @@ To access Flex Gateway runtime logs in Runtime Manager: == See Also -* xref:flex-view-logs-monitoring.adoc[] +* xref:flex-view-logs-in-monitoring.adoc[] * xref:flex-third-party-logs-config.adoc[] From aa7c127fc78d7ad2353c583b0250143d21197512 Mon Sep 17 00:00:00 2001 From: Marina B Date: Mon, 25 Nov 2024 23:22:14 -0800 Subject: [PATCH 2/2] Eliminate partials from reg & run flex gateway (#716) Remove partials from reg & run topics --- .../_partials/task-reg-run-flex-gateway.adoc | 184 ++--- .../ROOT/pages/flex-conn-reg-run-app.adoc | 744 ++++++++++++++++-- .../ROOT/pages/flex-conn-reg-run-token.adoc | 693 ++++++++++++++-- .../ROOT/pages/flex-conn-reg-run-up.adoc | 726 +++++++++++++++-- .../modules/ROOT/pages/flex-conn-rep-run.adoc | 4 +- .../flex-gateway-k8-getting-started.adoc | 4 +- .../ROOT/pages/flex-local-reg-run-app.adoc | 705 +++++++++++++++-- .../ROOT/pages/flex-local-reg-run-token.adoc | 659 ++++++++++++++-- .../ROOT/pages/flex-local-reg-run-up.adoc | 684 ++++++++++++++-- .../ROOT/pages/flex-local-rep-run.adoc | 4 +- .../flex-view-logs-in-runtime-manager.adoc | 2 - 11 files changed, 3978 insertions(+), 431 deletions(-) diff --git a/gateway/1.9/modules/ROOT/pages/_partials/task-reg-run-flex-gateway.adoc b/gateway/1.9/modules/ROOT/pages/_partials/task-reg-run-flex-gateway.adoc index 07e0a3a06..33f76dc0f 100644 --- a/gateway/1.9/modules/ROOT/pages/_partials/task-reg-run-flex-gateway.adoc +++ b/gateway/1.9/modules/ROOT/pages/_partials/task-reg-run-flex-gateway.adoc @@ -1,113 +1,85 @@ // partial for registering in connected/local modes with a username and password, connected app, or a token, in a Docker container or as a Linux service -// tag::prerequisites-heading[] - -== Before You Begin - -Before registering Flex Gateway, you must complete the following tasks: -// end::prerequisites-heading[] -// tag::app-prerequisites[] - -* xref:access-management::connected-apps-developers.adoc#create-a-connected-app[Configure a Connected App] -** Include the following scopes: -*** Read Servers -*** Manage Servers -*** View Organization -** Save the *Id* and *Secret* of the Connected app you configure. - -// end::app-prerequisites[] -// tag::prerequisites[] - -* xref:flex-install.adoc[Install a Flex Gateway] -* Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint Platform admin -* Collect the following information from your Anypoint Platform instance: -** The *Organization ID* for the organization where you want to run Flex Gateway -+ -See xref:access-management::organization.adoc#find-your-organization-id[Find your Organization ID] for more information on how to find your Organization ID. - -// end::prerequisites[] -// tag::environment-prerequisites[] - -** The *Environment ID* for the environment where you want to run Flex Gateway -+ -See xref:api-manager::latest-overview-concept.adoc#what-api-manager-looks-like[What API Manager Looks Like] -for more information on how to find your Environment ID. - -// end::environment-prerequisites[] -// tag::token-prerequisites[] - -** The registration *token* for the environment in Anypoint Platform where you want to run Flex Gateway -+ -Navigate to Runtime Manager, select *Flex Gateway* in the left navigation, and click *Add Gateway* -to generate set of instructions that includes a command block with the registration token. - -// end::token-prerequisites[] -// tag::user-prerequisites[] - -** The *Username* and *Password* of a user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager - -// end::user-prerequisites[] // tag::app-container-heading[] == Register and Run with a Connected App in a Container // end::app-container-heading[] + // tag::user-container-heading[] == Register and Run with a Username and Password in a Container // end::user-container-heading[] + // tag::token-container-heading[] == Register and Run with a Token in a Container // end::token-container-heading[] + // tag::app-docker-heading[] === Register and Run with a Connected App in a Docker Container // end::app-docker-heading[] + // tag::user-docker-heading[] === Register and Run with a Username and Password in a Docker Container // end::user-docker-heading[] + // tag::token-docker-heading[] === Register and Run with a Token in a Docker Container // end::token-docker-heading[] + // tag::app-podman-heading[] === Register and Run with a Connected App in a Podman Container // end::app-podman-heading[] + // tag::user-podman-heading[] === Register and Run with a Username and Password in a Podman Container // end::user-podman-heading[] + // tag::token-podman-heading[] === Register and Run with a Token in a Podman Container // end::token-podman-heading[] + // tag::app-linux-heading[] == Register and Run with a Connected App as a Linux Service // end::app-linux-heading[] + // tag::user-linux-heading[] == Register and Run with a Username and Password as a Linux Service // end::user-linux-heading[] + // tag::token-linux-heading[] == Register and Run with a Token as a Linux Service // end::token-linux-heading[] + // tag::app-k8s-heading[] == Register and Run with a Connected App in a Kubernetes Cluster // end::app-k8s-heading[] + // tag::user-k8s-heading[] == Register and Run with a Username and Password in a Kubernetes Cluster // end::user-k8s-heading[] + // tag::token-k8s-heading[] == Register and Run with a Token in a Kubernetes Cluster // end::token-k8s-heading[] + // tag::app-openshift-heading[] == Register and Run with a Connected App in an OpenShift Cluster // end::app-openshift-heading[] + // tag::user-openshift-heading[] == Register and Run with a Username and Password in an OpenShift Cluster // end::user-openshift-heading[] + // tag::token-openshift-heading[] == Register and Run with a Token in an OpenShift Cluster // end::token-openshift-heading[] + // tag::note-openshift-k8[] From the command line, OpenShift procedures match Kubernetes procedures. // end::note-openshift-k8[] // logos and links to sections that _use anchors_ in install and reg/run pages + // tag::table-logos-links[] [cols="1a,1a,1a,1a"] |=== @@ -123,10 +95,12 @@ From the command line, OpenShift procedures match Kubernetes procedures. |=== // end::table-logos-links[] + // tag::table-containers-logos-heading[] You can register and run Flex Gateway for use in one of the following containers: // end::table-containers-logos-heading[] + // tag::table-containers-logos-links[] [cols="1a,1a"] |=== @@ -138,10 +112,11 @@ You can register and run Flex Gateway for use in one of the following containers |=== // end::table-containers-logos-links[] + // tag::reg-command-intro[] To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. // end::reg-command-intro[] -// + // tag::k8s-connected-intro[] In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) services. @@ -156,7 +131,7 @@ In Connected Mode, resource creation through `kubectl apply` is possible but res Configuration, Service, Extension, and PolicyBinding of types `tls`, `tls-inbound`, and `tls-outbound`. For more info about resources, see xref:flex-local-configuration-reference-guide.adoc[]. // end::k8s-connected-intro[] -// + // tag::k8s-local-intro[] In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic. @@ -178,6 +153,7 @@ To register Flex Gateway with Anypoint Platform, run the Docker registration com Before registering your Flex Gateway instance, collect information for the following registration command options: // end::sub-coll-info[] + // tag::sub-coll-info-container[] ==== Collect Your Registration Data @@ -185,25 +161,30 @@ Before registering your Flex Gateway instance, collect information for the follo Before registering your Flex Gateway instance, collect information for the following registration command options: // end::sub-coll-info-container[] + // tag::user-replace-content[] * `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager * `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager // end::user-replace-content[] + // tag::token-replace-content[] * `--token` = the registration token for your environment in Anypoint Platform // end::token-replace-content[] + // tag::app-replace-content[] * `--client-id` = the Id for the Connected App you configured in Access Management * `--client-secret` = the Secret for the Connected App you configured in Access Management // end::app-replace-content[] + // tag::environment-replace-content[] * `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run // end::environment-replace-content[] + // tag::replace-content[] * `--organization` = your Organization ID in Anypoint Platform @@ -216,6 +197,7 @@ If `split` is set to `true`, registration information is split into two files: ` * `my-gateway` = the name you want to assign the gateway cluster // end::replace-content[] + // tag::reg-command-heading[] === Register Flex Gateway @@ -223,6 +205,7 @@ If `split` is set to `true`, registration information is split into two files: ` Register your Flex Gateway instance using the data that you gathered for the command options. // end::reg-command-heading[] + // tag::reg-command-heading-container[] ==== Register Flex Gateway @@ -230,6 +213,7 @@ Register your Flex Gateway instance using the data that you gathered for the com Register your Flex Gateway instance using the data that you gathered for the command options. // end::reg-command-heading-container[] + // tag::reg-command-heading-intro[] You can register using one of the following container runtimes: @@ -238,6 +222,7 @@ You can register using one of the following container runtimes: // * <> // end::reg-command-heading-intro[] + // tag::reg-command-openshift-heading-intro[] You can register using one of the following container runtimes: @@ -246,66 +231,82 @@ You can register using one of the following container runtimes: // * <> // end::reg-command-openshift-heading-intro[] + // tag::docker-reg-command-heading-intro[] // ==== Docker Run the following command to register using Docker: // end::docker-reg-command-heading-intro[] + // tag::podman-reg-command-heading-intro[] // ==== Podman Run the following command to register using Podman: // end::podman-reg-command-heading-intro[] + // tag::docker-create-directory-note[] IMPORTANT: Create a new directory called `flex-registration` (or similar) and then run the registration command in this new directory. The command creates registration files in this location. // end::docker-create-directory-note[] + // tag::reg-command-1[] [source,ssh,subs=attributes+] ---- -# end::reg-command-1[] -# tag::docker-reg-command[] +// end::reg-command-1[] + +// tag::docker-reg-command[] docker run --entrypoint flexctl \ -v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ registration create \ -# end::docker-reg-command[] -# tag::podman-reg-command[] +// end::docker-reg-command[] + +// tag::podman-reg-command[] podman run --entrypoint flexctl --userns=keep-id \ -v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ registration create \ -# end::podman-reg-command[] -# tag::linux-reg-command[] +// end::podman-reg-command[] + +// tag::linux-reg-command[] flexctl registration create \ -# end::linux-reg-command[] -# tag::user-reg-command[] +// end::linux-reg-command[] + +// tag::user-reg-command[] --username= \ --password= \ -# end::user-reg-command[] -# tag::app-reg-command[] +// end::user-reg-command[] + +// tag::app-reg-command[] --client-id= \ --client-secret= \ -# end::app-reg-command[] -# tag::environment-reg-command[] +// end::app-reg-command[] + +// tag::environment-reg-command[] --environment= \ -# end::environment-reg-command[] -# tag::token-reg-command[] +// end::environment-reg-command[] + +// tag::token-reg-command[] --token= \ -# end::token-reg-command[] -# tag::connected-reg-command[] +// end::token-reg-command[] + +// tag::connected-reg-command[] --connected=true \ -# end::connected-reg-command[] -# tag::organization-reg-command[] +// end::connected-reg-command[] + +// tag::organization-reg-command[] --organization= \ -# end::organization-reg-command[] -# tag::output-reg-command-linux[] +// end::organization-reg-command[] + +// tag::output-reg-command-linux[] --output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \ -# end::output-reg-command-linux[] -# tag::output-reg-command-docker[] +// end::output-reg-command-linux[] + +// tag::output-reg-command-docker[] --output-directory=/registration \ -# end::output-reg-command-docker[] -# tag::reg-command-2[] +// end::output-reg-command-docker[] + +// tag::reg-command-2[] my-gateway ---- @@ -315,6 +316,7 @@ NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1. to your command. // end::reg-command-2[] + // tag::after-reg[] In the output directory, you should see the following new registration file(s): @@ -324,18 +326,11 @@ In the output directory, you should see the following new registration file(s): IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you can no longer connect your Flex Gateway. // end::after-reg[] -// tag::after-reg-2[] -// end::after-reg-2[] -// tag::linux-after-reg[] - -// end::linux-after-reg[] -// tag::k8s-after-reg[] - -// end::k8s-after-reg[] // tag::disconnected-after-reg[] In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. // end::disconnected-after-reg[] + // tag::start-command[] === Start Command @@ -351,6 +346,7 @@ mulesoft/flex-gateway ---- NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. // end::start-command[] + // tag::start-command-container[] ==== Start Command @@ -366,6 +362,7 @@ mulesoft/flex-gateway ---- NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. // end::start-command-container[] + // tag::podman-start-command[] ==== Start Command @@ -381,6 +378,7 @@ docker.io/mulesoft/flex-gateway ---- NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. // end::podman-start-command[] + // tag::start-command-local-intro[] ==== Start Command @@ -388,6 +386,7 @@ NOTE: Specify an optional name you want to assign to your Flex Replica by includ Run the following start command in the same directory where you ran the registration command: // end::start-command-local-intro[] + // tag::start-command-local[] [source,ssh,subs=attributes+] @@ -400,6 +399,7 @@ mulesoft/flex-gateway NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. // end::start-command-local[] + // tag::podman-start-command-local[] [source,ssh,subs=attributes+] @@ -412,6 +412,7 @@ docker.io/mulesoft/flex-gateway NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. // end::podman-start-command-local[] + // tag::start-command-local-valid[] The output logs should include this line: @@ -420,12 +421,7 @@ The output logs should include this line: [flex-gateway-envoy][info] all dependencies initialized. starting workers ---- // end::start-command-local-valid[] -// tag::create-config-folder-file[] -// end::create-config-folder-file[] -// tag::config-content[] - -// end::config-content[] // tag::linux-start-commands[] === Start Commands @@ -453,25 +449,30 @@ If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully ---- // end::linux-start-commands[] + // tag::k8s-install-flex-helm-chart-title[] === Install Helm Chart into the Namespace // end::k8s-install-flex-helm-chart-title[] + // tag::k8s-install-flex-helm-chart-intro-connected[] Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is present and connected to Anypoint Platform. // end::k8s-install-flex-helm-chart-intro-connected[] + // tag::k8s-install-flex-helm-chart-intro-local[] Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster. // end::k8s-install-flex-helm-chart-intro-local[] // + // tag::k8s-flex-helm-chart[] A Helm chart installs Flex Gateway, monitoring tools, and applications. // end::k8s-flex-helm-chart[] // + // tag::k8s-flex-helm-chart-add[] . Add a Helm repository named `flex-gateway` for your chart: @@ -507,10 +508,11 @@ Update Complete. ⎈Happy Helming!⎈ + If you have more than one Helm repository on your machine, the message in your terminal window lists all of the repositories. // end::k8s-flex-helm-chart-add[] + // tag::k8s-flex-helm-chart-deploy[] // PLEASE retain blank line before first step below -. Run the Helm command for deploying your gateway in {reg-mode} Mode: +. Run the Helm command for deploying your gateway in Connected Mode: + [source,helm] ---- @@ -543,10 +545,11 @@ TEST SUITE: None The `REVISION` value increments the `ingress` release by `1` each time you run this command with the same namespace, repository, and chart names. For example, if you run the command a second time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date of that revision. // do not add an empty new line here at end, please // end::k8s-flex-helm-chart-deploy[] + // tag::k8s-flex-helm-chart-deploy-local[] // PLEASE retain blank line before first step below -. Run the Helm command for deploying your gateway in {reg-mode} Mode: +. Run the Helm command for deploying your gateway in Local Mode: + [source,helm] ---- @@ -576,12 +579,14 @@ TEST SUITE: None The `REVISION` value increments the `ingress` release by `1` each time you run this command with the same namespace, repository, and chart names. For example, if you run the command a second time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date of that revision. // do not add an empty new line here at end, please // end::k8s-flex-helm-chart-deploy-local[] + // tag::gateway-connected[] In Runtime Manager, click *← Flex Gateway* in the left navigation to find your new gateway in the UI. Notice that your gateway's current status is *Connected*. Refresh the page, if necessary. NOTE: After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI. Otherwise, the UI continues to list the gateway even if it is no longer running or connected. // end::gateway-connected[] + // tag::helm-chart-options[] === Helm Chart Settings @@ -611,6 +616,7 @@ helm show readme flex-gateway/flex-gateway // end::helm-chart-options[] + // tag::links-to-openshift-reg-steps[] Complete the following steps: @@ -618,7 +624,7 @@ Complete the following steps: . <> . <> // end::links-to-openshift-reg-steps[] -// + // tag::links-to-k8s-reg-steps[] Complete the following steps: diff --git a/gateway/1.9/modules/ROOT/pages/flex-conn-reg-run-app.adoc b/gateway/1.9/modules/ROOT/pages/flex-conn-reg-run-app.adoc index 62d7eaefd..14ec16955 100644 --- a/gateway/1.9/modules/ROOT/pages/flex-conn-reg-run-app.adoc +++ b/gateway/1.9/modules/ROOT/pages/flex-conn-reg-run-app.adoc @@ -4,180 +4,810 @@ ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] :imagesdir: ../assets/images -:reg-mode: Connected + //table with tech logos and links (linux, docker, k8, openshift) -include::partial$task-reg-run-flex-gateway.adoc[tags=table-logos-links] +[cols="1a,1a,1a,1a"] +|=== +|image:install-linux-logo.png[20%,20%,xref="#linux"] +|image:install-container-logo.png[25%,25%,xref="#container"] +|image:install-kubernetes-logo.png[20%,20%,xref="#kubernetes"] +|image:install-openshift-logo.png[20%,20%,xref="#openshift"] + +|<> +|<> +|<> +|<> +|=== [[prereqs]] // Prerequisites -include::partial$task-reg-run-flex-gateway.adoc[tags=prerequisites-heading;app-prerequisites;prerequisites;environment-prerequisites] +== Before You Begin + +Before registering Flex Gateway, you must complete the following tasks: + +* xref:access-management::connected-apps-developers.adoc#create-a-connected-app[Configure a Connected App] +** Include the following scopes: +*** Read Servers +*** Manage Servers +*** View Organization +** Save the *Id* and *Secret* of the Connected app you configure. + +* xref:flex-install.adoc[Install a Flex Gateway] +* Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint Platform admin +* Collect the following information from your Anypoint Platform instance: +** The *Organization ID* for the organization where you want to run Flex Gateway ++ +See xref:access-management::organization.adoc#find-your-organization-id[Find your Organization ID] for more information on how to find your Organization ID. + +** The *Environment ID* for the environment where you want to run Flex Gateway ++ +See xref:api-manager::latest-overview-concept.adoc#what-api-manager-looks-like[What API Manager Looks Like] +for more information on how to find your Environment ID. [[linux]] // Register and run with a connected app as a Linux service -include::partial$task-reg-run-flex-gateway.adoc[tags=app-linux-heading] -include::partial$prerequisites.adoc[tag=intro] +== Register and Run with a Connected App as a Linux Service +Flex Gateway runs on the following Long Term Support (LTS) versions of Linux: * {empty} -include::partial$prerequisites.adoc[tag=amazon-linux] +Amazon Linux 2023 * {empty} -include::partial$prerequisites.adoc[tag=centos] +CentOS 8 * {empty} -include::partial$prerequisites.adoc[tag=debian] +Debian (Bullseye, Bookworm) * {empty} -include::partial$prerequisites.adoc[tag=red-hat] +Red Hat Enterprise Linux (9) * {empty} -include::partial$prerequisites.adoc[tag=red-hat-ibm] +Red Hat Enterprise Linux (9) on IBM Power (ppc64le) * {empty} -include::partial$prerequisites.adoc[tag=suse] +SUSE Linux Enterprise (SLES 15 SP3) * {empty} -include::partial$prerequisites.adoc[tag=suse-ibm] +SUSE Linux Enterprise (SLES 15 SP3) on IBM Power (ppc64le) * {empty} -include::partial$prerequisites.adoc[tag=ubuntu] +Ubuntu (Focal, Jammy) + +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--client-id` = the Id for the Connected App you configured in Access Management +* `--client-secret` = the Secret for the Connected App you configured in Access Management +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster + +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +[source,ssh,subs=attributes+] +---- +flexctl registration create \ +--client-id= \ +--client-secret= \ +--environment= \ +--connected=true \ +--organization= \ +--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-intro;app-replace-content;environment-replace-content;replace-content;reg-command-heading;reg-command-1;linux-reg-command;app-reg-command;environment-reg-command;connected-reg-command;organization-reg-command;output-reg-command-linux;reg-command-2;after-reg;linux-after-reg;disconnected-after-reg;create-config-folder-file;config-content;linux-start-commands;gateway-connected] +=== Start Commands + +Start Flex Gateway with the following command: + +[source,ssh] +---- +sudo systemctl start flex-gateway +---- + +Verify that the Flex Gateway service is running successfully: + +[source,ssh] +---- +systemctl list-units flex-gateway* +---- + +If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running. + +[source,text] +---- + UNIT LOAD ACTIVE SUB DESCRIPTION + flex-gateway.service loaded active running Application +---- + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your new gateway in the UI. Notice that your gateway's current status is *Connected*. Refresh the page, if necessary. + +NOTE: After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI. Otherwise, the UI continues to list the gateway even if it is no longer running or connected. [[container]] -include::partial$task-reg-run-flex-gateway.adoc[tags=app-container-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=table-containers-logos-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=table-containers-logos-links] +== Register and Run with a Connected App in a Container +You can register and run Flex Gateway for use in one of the following containers: +[cols="1a,1a"] +|=== +|image:install-docker-logo.png[15%,15%,xref="#docker"] +|image:install-podman-logo.png[12%,12%,xref="#podman"] + +|<> +|<> +|=== [[docker]] // Register and run with a connected app in a Docker container -include::partial$task-reg-run-flex-gateway.adoc[tags=app-docker-heading;reg-command-intro;sub-coll-info-container;app-replace-content;environment-replace-content;replace-content;reg-command-heading-container;docker-create-directory-note;reg-command-1;docker-reg-command;app-reg-command;environment-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;after-reg-2;disconnected-after-reg;start-command-container;gateway-connected] +=== Register and Run with a Connected App in a Docker Container +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +==== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--client-id` = the Id for the Connected App you configured in Access Management +* `--client-secret` = the Secret for the Connected App you configured in Access Management +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster + +==== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +IMPORTANT: Create a new directory called `flex-registration` (or similar) and then run the registration command in this new directory. The command creates registration files in this location. + +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--client-id= \ +--client-secret= \ +--environment= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. + +==== Start Command + +Run the following start command in the same directory where you ran the registration command: + +[source,ssh,subs=attributes+] +---- +docker run --rm \ +-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \ +-p 8080:8080 \ +mulesoft/flex-gateway +---- +NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your new gateway in the UI. Notice that your gateway's current status is *Connected*. Refresh the page, if necessary. + +NOTE: After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI. Otherwise, the UI continues to list the gateway even if it is no longer running or connected. // PODMAN [[podman]] // Register and run with a connected app in a Podman container -include::partial$task-reg-run-flex-gateway.adoc[tags=app-podman-heading;reg-command-intro;sub-coll-info-container;app-replace-content;environment-replace-content;replace-content;reg-command-heading-container;docker-create-directory-note;reg-command-1;podman-reg-command;app-reg-command;environment-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;after-reg-2;disconnected-after-reg;podman-start-command;gateway-connected] +=== Register and Run with a Connected App in a Podman Container +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +==== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--client-id` = the Id for the Connected App you configured in Access Management +* `--client-secret` = the Secret for the Connected App you configured in Access Management +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster + +==== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +IMPORTANT: Create a new directory called `flex-registration` (or similar) and then run the registration command in this new directory. The command creates registration files in this location. + +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--client-id= \ +--client-secret= \ +--environment= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. + +==== Start Command + +Run the following start command in the same directory where you ran the registration command: + +[source,ssh,subs=attributes+] +---- +podman run --rm \ +-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \ +-p 8080:8080 \ +docker.io/mulesoft/flex-gateway +---- +NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your new gateway in the UI. Notice that your gateway's current status is *Connected*. Refresh the page, if necessary. + +NOTE: After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI. Otherwise, the UI continues to list the gateway even if it is no longer running or connected. // KUBERNETES [[kubernetes]] // Register and run with a connected app in a Kubernetes cluster + //intro -// - overview -include::partial$task-reg-run-flex-gateway.adoc[tags=app-k8s-heading;k8s-install-flex-helm-chart-intro-connected] + +== Register and Run with a Connected App in a Kubernetes Cluster + +// - task overview +Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is present and connected to Anypoint Platform. + // - cluster-level access when rbac enabled -include::partial$prerequisites.adoc[tags=rbac-permission-k8] +When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC), you must have cluster-level permissions to permit installation of custom resource definitions (CRDs) used by Flex Gateway. + //- links to steps -include::partial$task-reg-run-flex-gateway.adoc[tags=links-to-k8s-reg-steps] +Complete the following steps: + +. <> +. <> +. <> //- connected mode supplemental info for k8 and openshift -include::partial$task-reg-run-flex-gateway.adoc[tag=k8s-connected-intro] + +In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) services. + +Most management takes place within Anypoint Platform: + +* Deploy APIs to your cluster. +* Apply policies and other configurations. +* Create resources (_with the exception_ of Configuration and Service resources). + +In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the following resource types: +Configuration, Service, Extension, and PolicyBinding of types `tls`, `tls-inbound`, and `tls-outbound`. For more info about resources, see xref:flex-local-configuration-reference-guide.adoc[]. [[options-k8s]] //sub collected info -include::partial$task-reg-run-flex-gateway.adoc[tags=sub-coll-info;app-replace-content;environment-replace-content;replace-content] +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--client-id` = the Id for the Connected App you configured in Access Management +* `--client-secret` = the Secret for the Connected App you configured in Access Management +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster [[reg-k8s]] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading-intro] +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +You can register using one of the following container runtimes: + +// * <> +// * <> [[docker-container-reg]] .*Docker* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=docker-reg-command-heading-intro] +// ==== Docker +Run the following command to register using Docker: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;docker-reg-command;app-reg-command;environment-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg;disconnected-after-reg] +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--client-id= \ +--client-secret= \ +--environment= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. + ==== [[podman-container-reg]] .*Podman* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=podman-reg-command-heading-intro] +// ==== Podman +Run the following command to register using Podman: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;podman-reg-command;app-reg-command;environment-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg;disconnected-after-reg] +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--client-id= \ +--client-secret= \ +--environment= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. + ==== [[deploy-k8s]] //install helm chart section //- title -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-title] + +=== Install Helm Chart into the Namespace + //- helm chart info -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart] -include::partial$prerequisites.adoc[tags=helm] -Refer to <> for configuration options. +A Helm chart installs Flex Gateway, monitoring tools, and applications. +A minimum Helm version of 3.0.0 is required. +Refer to <> for configuration options. + //- add chart repo and deploy flex via chart -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart-add;k8s-flex-helm-chart-deploy] +. Add a Helm repository named `flex-gateway` for your chart: ++ +[source,helm] +---- +helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm +---- ++ +The command either adds the repository or skips this process if a Helm repository with that name already exists on your machine: ++ +* If the repository is new, the command returns the following message: ++ +---- +"flex-gateway" has been added to your repositories +---- ++ +* If the repository already exists, the command returns the following message: ++ +---- +"flex-gateway" already exists with the same configuration, skipping +---- + +. Run `helm repo up`. ++ +The command returns the following message: ++ +---- +Hang tight while we grab the latest from your chart repositories... +...Successfully got an update from the "flex-gateway" chart repository +Update Complete. ⎈Happy Helming!⎈ +---- ++ +If you have more than one Helm repository on your machine, the message in your terminal window lists all of the repositories. +// PLEASE retain blank line before first step below + +. Run the Helm command for deploying your gateway in Connected Mode: ++ +[source,helm] +---- +helm -n gateway upgrade -i --create-namespace \ +ingress flex-gateway/flex-gateway \ +--set gateway.mode=connected \ +--set-file registration.content=registration.yaml +---- ++ +This command creates the `gateway` namespace and a release named `ingress` if they do not exist. You can use names of your choice for your namespace and release. The command syntax for the Helm repository and chart names is `/`. ++ +The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local Mode. ++ +When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must have the appropriate permissions to create a load balancer in your cloud. If the load balancer is not provisioned or has issues with the provisioning process, you must choose another type by changing the `service.type` property during the installation. ++ +NOTE: By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If there's no API deployed to your Flex Gateway instance, the readiness state is `false`. This isn’t an issue with custom readiness probe configurations. ++ +When successful, the command prints a message indicating an upgrade to your `ingress` release: ++ +---- +Release "ingress" does not exist. Installing it now. +NAME: ingress +LAST DEPLOYED: Mon Mar 20 21:36:19 2023 +NAMESPACE: gateway +STATUS: deployed +REVISION: 1 +TEST SUITE: None +---- ++ +The `REVISION` value increments the `ingress` release by `1` each time you run this command with the same namespace, repository, and chart names. For example, if you run the command a second time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date of that revision. +// do not add an empty new line here at end, please + //- for flex connected mode deployment only -include::partial$task-reg-run-flex-gateway.adoc[tags=gateway-connected] +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your new gateway in the UI. Notice that your gateway's current status is *Connected*. Refresh the page, if necessary. + +NOTE: After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI. Otherwise, the UI continues to list the gateway even if it is no longer running or connected. [[helm-options-k8s]] //helm config options -include::partial$task-reg-run-flex-gateway.adoc[tags=helm-chart-options] +=== Helm Chart Settings + +To modify the default Helm settings with new values, such as `resource` values for CPU and memory settings, see xref:flex-gateway-k8-change-helm-settings.adoc[]. For additional Helm chart configurations, see xref:flex-gateway-k8-management.adoc[]. + +Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings: + +* Open the *flex-gateway* page in https://artifacthub.io/packages/helm/flex-gateway/flex-gateway[ArtifactHUB^] +* Run `helm show values /` from a terminal window. ++ +.Example: +[source,kubernetes] +---- +helm show values flex-gateway/flex-gateway +---- ++ +The example returns _default_ values of a repository and chart with the same name. + +To view the Helm chart `README`, run `helm show readme /` from a terminal window. + +.Example: +[source,kubernetes] +---- +helm show readme flex-gateway/flex-gateway +---- // OPENSHIFT [[openshift]] // Register and run with a connected app in an OpenShift cluster //heading -include::partial$task-reg-run-flex-gateway.adoc[tags=app-openshift-heading] +== Register and Run with a Connected App in an OpenShift Cluster //task intro -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-intro-connected] +Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is present and connected to Anypoint Platform. //- cluster-level access when rbac enabled -include::partial$prerequisites.adoc[tags=rbac-permission-k8;rbac-role-openshift] + +When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC), you must have cluster-level permissions to permit installation of custom resource definitions (CRDs) used by Flex Gateway. +In OpenShift, the `cluster-admin` role provides this level of access. + //- note (openshift command line procedures same as k8) -include::partial$task-reg-run-flex-gateway.adoc[tags=note-openshift-k8] +From the command line, OpenShift procedures match Kubernetes procedures. //- links to steps -include::partial$task-reg-run-flex-gateway.adoc[tags=links-to-openshift-reg-steps] +Complete the following steps: + +. <> +. <> +. <> //- connected mode supplemental info for k8 and openshift -include::partial$task-reg-run-flex-gateway.adoc[tag=k8s-connected-intro] + +In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) services. + +Most management takes place within Anypoint Platform: + +* Deploy APIs to your cluster. +* Apply policies and other configurations. +* Create resources (_with the exception_ of Configuration and Service resources). + +In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the following resource types: +Configuration, Service, Extension, and PolicyBinding of types `tls`, `tls-inbound`, and `tls-outbound`. For more info about resources, see xref:flex-local-configuration-reference-guide.adoc[]. [[options-openshift]] //sub collected info -include::partial$task-reg-run-flex-gateway.adoc[tags=sub-coll-info;app-replace-content;environment-replace-content;replace-content] +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--client-id` = the Id for the Connected App you configured in Access Management +* `--client-secret` = the Secret for the Connected App you configured in Access Management +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster [[reg-openshift]] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading] +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-openshift-heading-intro] +You can register using one of the following container runtimes: + +// * <> +// * <> [[docker-openshift-container-reg]] .*Docker* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=docker-reg-command-heading-intro] +// ==== Docker +Run the following command to register using Docker: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;docker-reg-command;app-reg-command;environment-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg;disconnected-after-reg] +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--client-id= \ +--client-secret= \ +--environment= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. + ==== [[podman-openshift-container-reg]] .*Podman* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=podman-reg-command-heading-intro] +// ==== Podman +Run the following command to register using Podman: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;podman-reg-command;app-reg-command;environment-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg;disconnected-after-reg] +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--client-id= \ +--client-secret= \ +--environment= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. + ==== [[deploy-openshift]] //install helm chart section //- title -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-title] +=== Install Helm Chart into the Namespace + //- helm chart info -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart] -include::partial$prerequisites.adoc[tags=helm] +A Helm chart installs Flex Gateway, monitoring tools, and applications. +A minimum Helm version of 3.0.0 is required. Refer to <> for configuration options. + //- add chart repo and deploy flex via chart -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart-add;k8s-flex-helm-chart-deploy] +. Add a Helm repository named `flex-gateway` for your chart: ++ +[source,helm] +---- +helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm +---- ++ +The command either adds the repository or skips this process if a Helm repository with that name already exists on your machine: ++ +* If the repository is new, the command returns the following message: ++ +---- +"flex-gateway" has been added to your repositories +---- ++ +* If the repository already exists, the command returns the following message: ++ +---- +"flex-gateway" already exists with the same configuration, skipping +---- + +. Run `helm repo up`. ++ +The command returns the following message: ++ +---- +Hang tight while we grab the latest from your chart repositories... +...Successfully got an update from the "flex-gateway" chart repository +Update Complete. ⎈Happy Helming!⎈ +---- ++ +If you have more than one Helm repository on your machine, the message in your terminal window lists all of the repositories. +// PLEASE retain blank line before first step below + +. Run the Helm command for deploying your gateway in Connected Mode: ++ +[source,helm] +---- +helm -n gateway upgrade -i --create-namespace \ +ingress flex-gateway/flex-gateway \ +--set gateway.mode=connected \ +--set-file registration.content=registration.yaml +---- ++ +This command creates the `gateway` namespace and a release named `ingress` if they do not exist. You can use names of your choice for your namespace and release. The command syntax for the Helm repository and chart names is `/`. ++ +The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local Mode. ++ +When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must have the appropriate permissions to create a load balancer in your cloud. If the load balancer is not provisioned or has issues with the provisioning process, you must choose another type by changing the `service.type` property during the installation. ++ +NOTE: By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If there's no API deployed to your Flex Gateway instance, the readiness state is `false`. This isn’t an issue with custom readiness probe configurations. ++ +When successful, the command prints a message indicating an upgrade to your `ingress` release: ++ +---- +Release "ingress" does not exist. Installing it now. +NAME: ingress +LAST DEPLOYED: Mon Mar 20 21:36:19 2023 +NAMESPACE: gateway +STATUS: deployed +REVISION: 1 +TEST SUITE: None +---- ++ +The `REVISION` value increments the `ingress` release by `1` each time you run this command with the same namespace, repository, and chart names. For example, if you run the command a second time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date of that revision. +// do not add an empty new line here at end, please + //- for flex connected mode deployment only -include::partial$task-reg-run-flex-gateway.adoc[tags=gateway-connected] +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your new gateway in the UI. Notice that your gateway's current status is *Connected*. Refresh the page, if necessary. + +NOTE: After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI. Otherwise, the UI continues to list the gateway even if it is no longer running or connected. [[helm-options-openshift]] //helm config options -include::partial$task-reg-run-flex-gateway.adoc[tags=helm-chart-options] +=== Helm Chart Settings + +To modify the default Helm settings with new values, such as `resource` values for CPU and memory settings, see xref:flex-gateway-k8-change-helm-settings.adoc[]. For additional Helm chart configurations, see xref:flex-gateway-k8-management.adoc[]. + +Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings: + +* Open the *flex-gateway* page in https://artifacthub.io/packages/helm/flex-gateway/flex-gateway[ArtifactHUB^] +* Run `helm show values /` from a terminal window. ++ +.Example: +[source,kubernetes] +---- +helm show values flex-gateway/flex-gateway +---- ++ +The example returns _default_ values of a repository and chart with the same name. + +To view the Helm chart `README`, run `helm show readme /` from a terminal window. + +.Example: +[source,kubernetes] +---- +helm show readme flex-gateway/flex-gateway +---- == See Also diff --git a/gateway/1.9/modules/ROOT/pages/flex-conn-reg-run-token.adoc b/gateway/1.9/modules/ROOT/pages/flex-conn-reg-run-token.adoc index eb022d17b..13e5b27d7 100644 --- a/gateway/1.9/modules/ROOT/pages/flex-conn-reg-run-token.adoc +++ b/gateway/1.9/modules/ROOT/pages/flex-conn-reg-run-token.adoc @@ -3,183 +3,760 @@ ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] :imagesdir: ../assets/images -:reg-mode: Connected + //table with tech logos and links (linux, docker, k8, openshift) -include::partial$task-reg-run-flex-gateway.adoc[tags=table-logos-links] +[cols="1a,1a,1a,1a"] +|=== +|image:install-linux-logo.png[20%,20%,xref="#linux"] +|image:install-container-logo.png[25%,25%,xref="#container"] +|image:install-kubernetes-logo.png[20%,20%,xref="#kubernetes"] +|image:install-openshift-logo.png[20%,20%,xref="#openshift"] + +|<> +|<> +|<> +|<> +|=== [[prereqs]] // Prerequisites -include::partial$task-reg-run-flex-gateway.adoc[tags=prerequisites-heading;prerequisites;token-prerequisites] +== Before You Begin + +Before registering Flex Gateway, you must complete the following tasks: + +* xref:flex-install.adoc[Install a Flex Gateway] +* Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint Platform admin +* Collect the following information from your Anypoint Platform instance: +** The *Organization ID* for the organization where you want to run Flex Gateway ++ +See xref:access-management::organization.adoc#find-your-organization-id[Find your Organization ID] for more information on how to find your Organization ID. + +** The registration *token* for the environment in Anypoint Platform where you want to run Flex Gateway ++ +Navigate to Runtime Manager, select *Flex Gateway* in the left navigation, and click *Add Gateway* +to generate set of instructions that includes a command block with the registration token. [[linux]] // Register and run with a token as a Linux service -include::partial$task-reg-run-flex-gateway.adoc[tags=token-linux-heading] -include::partial$prerequisites.adoc[tag=intro] +== Register and Run with a Token as a Linux Service +Flex Gateway runs on the following Long Term Support (LTS) versions of Linux: * {empty} -include::partial$prerequisites.adoc[tag=amazon-linux] +Amazon Linux 2023 * {empty} -include::partial$prerequisites.adoc[tag=centos] +CentOS 8 * {empty} -include::partial$prerequisites.adoc[tag=debian] +Debian (Bullseye, Bookworm) * {empty} -include::partial$prerequisites.adoc[tag=red-hat] +Red Hat Enterprise Linux (9) * {empty} -include::partial$prerequisites.adoc[tag=red-hat-ibm] +Red Hat Enterprise Linux (9) on IBM Power (ppc64le) * {empty} -include::partial$prerequisites.adoc[tag=suse] +SUSE Linux Enterprise (SLES 15 SP3) * {empty} -include::partial$prerequisites.adoc[tag=suse-ibm] +SUSE Linux Enterprise (SLES 15 SP3) on IBM Power (ppc64le) * {empty} -include::partial$prerequisites.adoc[tag=ubuntu] +Ubuntu (Focal, Jammy) + +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--token` = the registration token for your environment in Anypoint Platform +* `--organization` = your Organization ID in Anypoint Platform +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output +* `my-gateway` = the name you want to assign the gateway cluster + +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. +[source,ssh,subs=attributes+] +---- +flexctl registration create \ +--token= \ +--connected=true \ +--organization= \ +--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-intro;sub-coll-info;token-replace-content;replace-content;reg-command-heading;reg-command-1;linux-reg-command;token-reg-command;connected-reg-command;organization-reg-command;output-reg-command-linux;reg-command-2;after-reg;linux-after-reg;disconnected-after-reg;create-config-folder-file;config-content;linux-start-commands;gateway-connected] +=== Start Commands + +Start Flex Gateway with the following command: + +[source,ssh] +---- +sudo systemctl start flex-gateway +---- + +Verify that the Flex Gateway service is running successfully: + +[source,ssh] +---- +systemctl list-units flex-gateway* +---- + +If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running. + +[source,text] +---- + UNIT LOAD ACTIVE SUB DESCRIPTION + flex-gateway.service loaded active running Application +---- +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your new gateway in the UI. Notice that your gateway's current status is *Connected*. Refresh the page, if necessary. + +NOTE: After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI. Otherwise, the UI continues to list the gateway even if it is no longer running or connected. [[container]] -include::partial$task-reg-run-flex-gateway.adoc[tags=token-container-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=table-containers-logos-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=table-containers-logos-links] +== Register and Run with a Token in a Container +You can register and run Flex Gateway for use in one of the following containers: +[cols="1a,1a"] +|=== +|image:install-docker-logo.png[15%,15%,xref="#docker"] +|image:install-podman-logo.png[12%,12%,xref="#podman"] + +|<> +|<> +|=== [[docker]] // Register and run with a token in a Docker container -include::partial$task-reg-run-flex-gateway.adoc[tags=token-docker-heading;reg-command-intro;sub-coll-info-container;token-replace-content;replace-content;reg-command-heading-container;docker-create-directory-note;reg-command-1;docker-reg-command;token-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;after-reg-2;disconnected-after-reg;start-command-container;gateway-connected] +=== Register and Run with a Token in a Docker Container +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +==== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--token` = the registration token for your environment in Anypoint Platform +* `--organization` = your Organization ID in Anypoint Platform +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output +* `my-gateway` = the name you want to assign the gateway cluster + +==== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +IMPORTANT: Create a new directory called `flex-registration` (or similar) and then run the registration command in this new directory. The command creates registration files in this location. +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--token= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. + +==== Start Command + +Run the following start command in the same directory where you ran the registration command: + +[source,ssh,subs=attributes+] +---- +docker run --rm \ +-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \ +-p 8080:8080 \ +mulesoft/flex-gateway +---- +NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your new gateway in the UI. Notice that your gateway's current status is *Connected*. Refresh the page, if necessary. + +NOTE: After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI. Otherwise, the UI continues to list the gateway even if it is no longer running or connected. // PODMAN [[podman]] // Register and run with a token in a Podman container -include::partial$task-reg-run-flex-gateway.adoc[tags=token-podman-heading;reg-command-intro;sub-coll-info-container;token-replace-content;replace-content;reg-command-heading-container;docker-create-directory-note;reg-command-1;podman-reg-command;token-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;after-reg-2;disconnected-after-reg;podman-start-command;gateway-connected] +=== Register and Run with a Token in a Podman Container +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +==== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--token` = the registration token for your environment in Anypoint Platform +* `--organization` = your Organization ID in Anypoint Platform +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output +* `my-gateway` = the name you want to assign the gateway cluster + +==== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +IMPORTANT: Create a new directory called `flex-registration` (or similar) and then run the registration command in this new directory. The command creates registration files in this location. +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--token= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. + +==== Start Command + +Run the following start command in the same directory where you ran the registration command: + +[source,ssh,subs=attributes+] +---- +podman run --rm \ +-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \ +-p 8080:8080 \ +docker.io/mulesoft/flex-gateway +---- +NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your new gateway in the UI. Notice that your gateway's current status is *Connected*. Refresh the page, if necessary. + +NOTE: After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI. Otherwise, the UI continues to list the gateway even if it is no longer running or connected. // KUBERNETES [[kubernetes]] // Register and run with a token in a Kubernetes cluster //heading -include::partial$task-reg-run-flex-gateway.adoc[tags=token-k8s-heading] + +== Register and Run with a Token in a Kubernetes Cluster // - task overview -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-intro-connected] +Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is present and connected to Anypoint Platform. + // - cluster-level access when rbac enabled -include::partial$prerequisites.adoc[tags=rbac-permission-k8] +When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC), you must have cluster-level permissions to permit installation of custom resource definitions (CRDs) used by Flex Gateway. + //- links to steps -include::partial$task-reg-run-flex-gateway.adoc[tags=links-to-k8s-reg-steps] +Complete the following steps: + +. <> +. <> +. <> + //- connected mode supplemental info for k8 and openshift -include::partial$task-reg-run-flex-gateway.adoc[tag=k8s-connected-intro] +In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) services. + +Most management takes place within Anypoint Platform: + +* Deploy APIs to your cluster. +* Apply policies and other configurations. +* Create resources (_with the exception_ of Configuration and Service resources). + +In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the following resource types: +Configuration, Service, Extension, and PolicyBinding of types `tls`, `tls-inbound`, and `tls-outbound`. For more info about resources, see xref:flex-local-configuration-reference-guide.adoc[]. [[options-k8s]] //sub collected info -include::partial$task-reg-run-flex-gateway.adoc[tags=sub-coll-info;token-replace-content;replace-content] + +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--token` = the registration token for your environment in Anypoint Platform +* `--organization` = your Organization ID in Anypoint Platform +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output +* `my-gateway` = the name you want to assign the gateway cluster [[reg-k8s]] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading-intro] +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +You can register using one of the following container runtimes: + +// * <> +// * <> [[docker-container-reg]] .*Docker* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=docker-reg-command-heading-intro] +// ==== Docker +Run the following command to register using Docker: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;docker-reg-command;token-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg;disconnected-after-reg] +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--token= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. ==== [[podman-container-reg]] .*Podman* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=podman-reg-command-heading-intro] +// ==== Podman +Run the following command to register using Podman: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;podman-reg-command;token-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg;disconnected-after-reg] +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--token= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. ==== [[deploy-k8s]] //install helm chart section //- title -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-title] +=== Install Helm Chart into the Namespace + //- helm chart info -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart] -include::partial$prerequisites.adoc[tags=helm] -Refer to <> for configuration options. +A Helm chart installs Flex Gateway, monitoring tools, and applications. +A minimum Helm version of 3.0.0 is required. +Refer to <> for configuration options. + //- add chart repo and deploy flex via chart -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart-add;k8s-flex-helm-chart-deploy] +. Add a Helm repository named `flex-gateway` for your chart: ++ +[source,helm] +---- +helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm +---- ++ +The command either adds the repository or skips this process if a Helm repository with that name already exists on your machine: ++ +* If the repository is new, the command returns the following message: ++ +---- +"flex-gateway" has been added to your repositories +---- ++ +* If the repository already exists, the command returns the following message: ++ +---- +"flex-gateway" already exists with the same configuration, skipping +---- + +. Run `helm repo up`. ++ +The command returns the following message: ++ +---- +Hang tight while we grab the latest from your chart repositories... +...Successfully got an update from the "flex-gateway" chart repository +Update Complete. ⎈Happy Helming!⎈ +---- ++ +If you have more than one Helm repository on your machine, the message in your terminal window lists all of the repositories. +// PLEASE retain blank line before first step below + +. Run the Helm command for deploying your gateway in Connected Mode: ++ +[source,helm] +---- +helm -n gateway upgrade -i --create-namespace \ +ingress flex-gateway/flex-gateway \ +--set gateway.mode=connected \ +--set-file registration.content=registration.yaml +---- ++ +This command creates the `gateway` namespace and a release named `ingress` if they do not exist. You can use names of your choice for your namespace and release. The command syntax for the Helm repository and chart names is `/`. ++ +The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local Mode. ++ +When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must have the appropriate permissions to create a load balancer in your cloud. If the load balancer is not provisioned or has issues with the provisioning process, you must choose another type by changing the `service.type` property during the installation. ++ +NOTE: By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If there's no API deployed to your Flex Gateway instance, the readiness state is `false`. This isn’t an issue with custom readiness probe configurations. ++ +When successful, the command prints a message indicating an upgrade to your `ingress` release: ++ +---- +Release "ingress" does not exist. Installing it now. +NAME: ingress +LAST DEPLOYED: Mon Mar 20 21:36:19 2023 +NAMESPACE: gateway +STATUS: deployed +REVISION: 1 +TEST SUITE: None +---- ++ +The `REVISION` value increments the `ingress` release by `1` each time you run this command with the same namespace, repository, and chart names. For example, if you run the command a second time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date of that revision. +// do not add an empty new line here at end, please + //- for flex connected mode deployment only -include::partial$task-reg-run-flex-gateway.adoc[tags=gateway-connected] +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your new gateway in the UI. Notice that your gateway's current status is *Connected*. Refresh the page, if necessary. + +NOTE: After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI. Otherwise, the UI continues to list the gateway even if it is no longer running or connected. [[helm-options-k8s]] //helm config options -include::partial$task-reg-run-flex-gateway.adoc[tags=helm-chart-options] +=== Helm Chart Settings + +To modify the default Helm settings with new values, such as `resource` values for CPU and memory settings, see xref:flex-gateway-k8-change-helm-settings.adoc[]. For additional Helm chart configurations, see xref:flex-gateway-k8-management.adoc[]. + +Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings: + +* Open the *flex-gateway* page in https://artifacthub.io/packages/helm/flex-gateway/flex-gateway[ArtifactHUB^] +* Run `helm show values /` from a terminal window. ++ +.Example: +[source,kubernetes] +---- +helm show values flex-gateway/flex-gateway +---- ++ +The example returns _default_ values of a repository and chart with the same name. + +To view the Helm chart `README`, run `helm show readme /` from a terminal window. + +.Example: +[source,kubernetes] +---- +helm show readme flex-gateway/flex-gateway +---- // OPENSHIFT [[openshift]] // Register and run with a token in an OpenShift cluster //heading -include::partial$task-reg-run-flex-gateway.adoc[tags=token-openshift-heading] +== Register and Run with a Token in an OpenShift Cluster //intro -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-intro-connected] +Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is present and connected to Anypoint Platform. + //- cluster-level access when rbac enabled -include::partial$prerequisites.adoc[tags=rbac-permission-k8;rbac-role-openshift] +When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC), you must have cluster-level permissions to permit installation of custom resource definitions (CRDs) used by Flex Gateway. +In OpenShift, the `cluster-admin` role provides this level of access. + //- note (openshift command line procedures same as k8) -include::partial$task-reg-run-flex-gateway.adoc[tags=note-openshift-k8] +From the command line, OpenShift procedures match Kubernetes procedures. //- links to steps -include::partial$task-reg-run-flex-gateway.adoc[tags=links-to-openshift-reg-steps] +Complete the following steps: + +. <> +. <> +. <> //- connected mode supplemental info for k8 and openshift -include::partial$task-reg-run-flex-gateway.adoc[tag=k8s-connected-intro] +In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) services. + +Most management takes place within Anypoint Platform: + +* Deploy APIs to your cluster. +* Apply policies and other configurations. +* Create resources (_with the exception_ of Configuration and Service resources). + +In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the following resource types: +Configuration, Service, Extension, and PolicyBinding of types `tls`, `tls-inbound`, and `tls-outbound`. For more info about resources, see xref:flex-local-configuration-reference-guide.adoc[]. [[options-openshift]] //sub collected info -include::partial$task-reg-run-flex-gateway.adoc[tags=sub-coll-info;token-replace-content;replace-content] +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--token` = the registration token for your environment in Anypoint Platform +* `--organization` = your Organization ID in Anypoint Platform +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output +* `my-gateway` = the name you want to assign the gateway cluster [[reg-openshift]] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading] +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +You can register using one of the following container runtimes: -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-openshift-heading-intro] +// * <> +// * <> [[docker-openshift-container-reg]] .*Docker* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=docker-reg-command-heading-intro] +// ==== Docker +Run the following command to register using Docker: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;docker-reg-command;token-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg;disconnected-after-reg] +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--token= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. ==== [[podman-openshift-container-reg]] .*Podman* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=podman-reg-command-heading-intro] +// ==== Podman +Run the following command to register using Podman: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;podman-reg-command;token-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg;disconnected-after-reg] +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--token= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. ==== [[deploy-openshift]] //install helm chart section //- title -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-title] +=== Install Helm Chart into the Namespace + //- helm chart info -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart] -include::partial$prerequisites.adoc[tags=helm] +A Helm chart installs Flex Gateway, monitoring tools, and applications. +A minimum Helm version of 3.0.0 is required. Refer to <> for configuration options. + //- add chart repo and deploy flex via chart -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart-add;k8s-flex-helm-chart-deploy] +. Add a Helm repository named `flex-gateway` for your chart: ++ +[source,helm] +---- +helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm +---- ++ +The command either adds the repository or skips this process if a Helm repository with that name already exists on your machine: ++ +* If the repository is new, the command returns the following message: ++ +---- +"flex-gateway" has been added to your repositories +---- ++ +* If the repository already exists, the command returns the following message: ++ +---- +"flex-gateway" already exists with the same configuration, skipping +---- + +. Run `helm repo up`. ++ +The command returns the following message: ++ +---- +Hang tight while we grab the latest from your chart repositories... +...Successfully got an update from the "flex-gateway" chart repository +Update Complete. ⎈Happy Helming!⎈ +---- ++ +If you have more than one Helm repository on your machine, the message in your terminal window lists all of the repositories. +// PLEASE retain blank line before first step below + +. Run the Helm command for deploying your gateway in Connected Mode: ++ +[source,helm] +---- +helm -n gateway upgrade -i --create-namespace \ +ingress flex-gateway/flex-gateway \ +--set gateway.mode=connected \ +--set-file registration.content=registration.yaml +---- ++ +This command creates the `gateway` namespace and a release named `ingress` if they do not exist. You can use names of your choice for your namespace and release. The command syntax for the Helm repository and chart names is `/`. ++ +The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local Mode. ++ +When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must have the appropriate permissions to create a load balancer in your cloud. If the load balancer is not provisioned or has issues with the provisioning process, you must choose another type by changing the `service.type` property during the installation. ++ +NOTE: By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If there's no API deployed to your Flex Gateway instance, the readiness state is `false`. This isn’t an issue with custom readiness probe configurations. ++ +When successful, the command prints a message indicating an upgrade to your `ingress` release: ++ +---- +Release "ingress" does not exist. Installing it now. +NAME: ingress +LAST DEPLOYED: Mon Mar 20 21:36:19 2023 +NAMESPACE: gateway +STATUS: deployed +REVISION: 1 +TEST SUITE: None +---- ++ +The `REVISION` value increments the `ingress` release by `1` each time you run this command with the same namespace, repository, and chart names. For example, if you run the command a second time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date of that revision. +// do not add an empty new line here at end, please + //- for flex connected mode deployment only -include::partial$task-reg-run-flex-gateway.adoc[tags=gateway-connected] +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your new gateway in the UI. Notice that your gateway's current status is *Connected*. Refresh the page, if necessary. + +NOTE: After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI. Otherwise, the UI continues to list the gateway even if it is no longer running or connected. [[helm-options-openshift]] //helm config options -include::partial$task-reg-run-flex-gateway.adoc[tags=helm-chart-options] - +=== Helm Chart Settings + +To modify the default Helm settings with new values, such as `resource` values for CPU and memory settings, see xref:flex-gateway-k8-change-helm-settings.adoc[]. For additional Helm chart configurations, see xref:flex-gateway-k8-management.adoc[]. + +Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings: + +* Open the *flex-gateway* page in https://artifacthub.io/packages/helm/flex-gateway/flex-gateway[ArtifactHUB^] +* Run `helm show values /` from a terminal window. ++ +.Example: +[source,kubernetes] +---- +helm show values flex-gateway/flex-gateway +---- ++ +The example returns _default_ values of a repository and chart with the same name. + +To view the Helm chart `README`, run `helm show readme /` from a terminal window. + +.Example: +[source,kubernetes] +---- +helm show readme flex-gateway/flex-gateway +---- == See Also diff --git a/gateway/1.9/modules/ROOT/pages/flex-conn-reg-run-up.adoc b/gateway/1.9/modules/ROOT/pages/flex-conn-reg-run-up.adoc index 4068bf931..8d454b72a 100644 --- a/gateway/1.9/modules/ROOT/pages/flex-conn-reg-run-up.adoc +++ b/gateway/1.9/modules/ROOT/pages/flex-conn-reg-run-up.adoc @@ -3,182 +3,796 @@ ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] :imagesdir: ../assets/images -:reg-mode: Connected + //table with tech logos and links (linux, docker, k8, openshift) -include::partial$task-reg-run-flex-gateway.adoc[tags=table-logos-links] +[cols="1a,1a,1a,1a"] +|=== +|image:install-linux-logo.png[20%,20%,xref="#linux"] +|image:install-container-logo.png[25%,25%,xref="#container"] +|image:install-kubernetes-logo.png[20%,20%,xref="#kubernetes"] +|image:install-openshift-logo.png[20%,20%,xref="#openshift"] + +|<> +|<> +|<> +|<> +|=== [[prereqs]] // Prerequisites -include::partial$task-reg-run-flex-gateway.adoc[tags=prerequisites-heading;prerequisites;environment-prerequisites;user-prerequisites] +== Before You Begin + +Before registering Flex Gateway, you must complete the following tasks: + +* xref:flex-install.adoc[Install a Flex Gateway] +* Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint Platform admin +* Collect the following information from your Anypoint Platform instance: +** The *Organization ID* for the organization where you want to run Flex Gateway ++ +See xref:access-management::organization.adoc#find-your-organization-id[Find your Organization ID] for more information on how to find your Organization ID. + +** The *Environment ID* for the environment where you want to run Flex Gateway ++ +See xref:api-manager::latest-overview-concept.adoc#what-api-manager-looks-like[What API Manager Looks Like] +for more information on how to find your Environment ID. + +** The *Username* and *Password* of a user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager [[linux]] // Register and run with a username and password as a Linux service -include::partial$task-reg-run-flex-gateway.adoc[tags=user-linux-heading] -include::partial$prerequisites.adoc[tag=intro] +== Register and Run with a Username and Password as a Linux Service +Flex Gateway runs on the following Long Term Support (LTS) versions of Linux: * {empty} -include::partial$prerequisites.adoc[tag=amazon-linux] +Amazon Linux 2023 * {empty} -include::partial$prerequisites.adoc[tag=centos] +CentOS 8 * {empty} -include::partial$prerequisites.adoc[tag=debian] +Debian (Bullseye, Bookworm) * {empty} -include::partial$prerequisites.adoc[tag=red-hat] +Red Hat Enterprise Linux (9) * {empty} -include::partial$prerequisites.adoc[tag=red-hat-ibm] +Red Hat Enterprise Linux (9) on IBM Power (ppc64le) * {empty} -include::partial$prerequisites.adoc[tag=suse] +SUSE Linux Enterprise (SLES 15 SP3) * {empty} -include::partial$prerequisites.adoc[tag=suse-ibm] +SUSE Linux Enterprise (SLES 15 SP3) on IBM Power (ppc64le) * {empty} -include::partial$prerequisites.adoc[tag=ubuntu] +Ubuntu (Focal, Jammy) + + +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster + +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. +[source,ssh,subs=attributes+] +---- +flexctl registration create \ +--username= \ +--password= \ +--environment= \ +--connected=true \ +--organization= \ +--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-intro;user-replace-content;environment-replace-content;replace-content;reg-command-heading;reg-command-1;linux-reg-command;user-reg-command;environment-reg-command;connected-reg-command;organization-reg-command;output-reg-command-linux;reg-command-2;after-reg;linux-after-reg;disconnected-after-reg;create-config-folder-file;config-content;linux-start-commands;gateway-connected] +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. + + +=== Start Commands + +Start Flex Gateway with the following command: + +[source,ssh] +---- +sudo systemctl start flex-gateway +---- + +Verify that the Flex Gateway service is running successfully: + +[source,ssh] +---- +systemctl list-units flex-gateway* +---- + +If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running. + +[source,text] +---- + UNIT LOAD ACTIVE SUB DESCRIPTION + flex-gateway.service loaded active running Application +---- +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your new gateway in the UI. Notice that your gateway's current status is *Connected*. Refresh the page, if necessary. + +NOTE: After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI. Otherwise, the UI continues to list the gateway even if it is no longer running or connected. [[container]] -include::partial$task-reg-run-flex-gateway.adoc[tags=user-container-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=table-containers-logos-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=table-containers-logos-links] +== Register and Run with a Username and Password in a Container +You can register and run Flex Gateway for use in one of the following containers: +[cols="1a,1a"] +|=== +|image:install-docker-logo.png[15%,15%,xref="#docker"] +|image:install-podman-logo.png[12%,12%,xref="#podman"] + +|<> +|<> +|=== [[docker]] // Register and run with a username and password in a Docker container -include::partial$task-reg-run-flex-gateway.adoc[tags=user-docker-heading;reg-command-intro;sub-coll-info-container;user-replace-content;environment-replace-content;replace-content;reg-command-heading-container;docker-create-directory-note;reg-command-1;docker-reg-command;user-reg-command;environment-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;after-reg-2;disconnected-after-reg;start-command-container;gateway-connected] +=== Register and Run with a Username and Password in a Docker Container +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +==== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output +* `my-gateway` = the name you want to assign the gateway cluster + +==== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +IMPORTANT: Create a new directory called `flex-registration` (or similar) and then run the registration command in this new directory. The command creates registration files in this location. +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--username= \ +--password= \ +--environment= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. + +==== Start Command + +Run the following start command in the same directory where you ran the registration command: + +[source,ssh,subs=attributes+] +---- +docker run --rm \ +-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \ +-p 8080:8080 \ +mulesoft/flex-gateway +---- +NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your new gateway in the UI. Notice that your gateway's current status is *Connected*. Refresh the page, if necessary. + +NOTE: After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI. Otherwise, the UI continues to list the gateway even if it is no longer running or connected. // PODMAN [[podman]] // Register and run with a username and password in a Podman container -include::partial$task-reg-run-flex-gateway.adoc[tags=user-podman-heading;reg-command-intro;sub-coll-info-container;user-replace-content;environment-replace-content;replace-content;reg-command-heading-container;docker-create-directory-note;reg-command-1;podman-reg-command;user-reg-command;environment-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;after-reg-2;disconnected-after-reg;podman-start-command;gateway-connected] +=== Register and Run with a Username and Password in a Podman Container +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +==== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output +* `my-gateway` = the name you want to assign the gateway cluster + +==== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +IMPORTANT: Create a new directory called `flex-registration` (or similar) and then run the registration command in this new directory. The command creates registration files in this location. +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--username= \ +--password= \ +--environment= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. + +==== Start Command + +Run the following start command in the same directory where you ran the registration command: + +[source,ssh,subs=attributes+] +---- +podman run --rm \ +-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \ +-p 8080:8080 \ +docker.io/mulesoft/flex-gateway +---- +NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your new gateway in the UI. Notice that your gateway's current status is *Connected*. Refresh the page, if necessary. + +NOTE: After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI. Otherwise, the UI continues to list the gateway even if it is no longer running or connected. // KUBERNETES [[kubernetes]] // Register and run with a username and password in a Kubernetes cluster //heading -include::partial$task-reg-run-flex-gateway.adoc[tags=user-k8s-heading] +== Register and Run with a Username and Password in a Kubernetes Cluster // - task overview -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-intro-connected] +Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is present and connected to Anypoint Platform. + // - cluster-level access when rbac enabled -include::partial$prerequisites.adoc[tags=rbac-permission-k8] +When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC), you must have cluster-level permissions to permit installation of custom resource definitions (CRDs) used by Flex Gateway. + //- links to steps -include::partial$task-reg-run-flex-gateway.adoc[tags=links-to-k8s-reg-steps] +Complete the following steps: + +. <> +. <> +. <> + //- connected mode supplemental info for k8 and openshift -include::partial$task-reg-run-flex-gateway.adoc[tag=k8s-connected-intro] +In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) services. + +Most management takes place within Anypoint Platform: + +* Deploy APIs to your cluster. +* Apply policies and other configurations. +* Create resources (_with the exception_ of Configuration and Service resources). + +In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the following resource types: +Configuration, Service, Extension, and PolicyBinding of types `tls`, `tls-inbound`, and `tls-outbound`. For more info about resources, see xref:flex-local-configuration-reference-guide.adoc[]. //sub collected info [[options-k8s]] -include::partial$task-reg-run-flex-gateway.adoc[tags=sub-coll-info;user-replace-content;environment-replace-content;replace-content] +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster [[reg-k8s]] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading-intro] +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +You can register using one of the following container runtimes: + +// * <> +// * <> [[docker-container-reg]] .*Docker* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=docker-reg-command-heading-intro] +// ==== Docker +Run the following command to register using Docker: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;docker-reg-command;user-reg-command;environment-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg;disconnected-after-reg] +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--username= \ +--password= \ +--environment= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. + ==== [[podman-container-reg]] .*Podman* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=podman-reg-command-heading-intro] +// ==== Podman +Run the following command to register using Podman: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;podman-reg-command;user-reg-command;environment-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg;disconnected-after-reg] +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--username= \ +--password= \ +--environment= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. + ==== [[deploy-k8s]] //install helm chart section //- title -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-title] +=== Install Helm Chart into the Namespace //- helm chart info -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart] -include::partial$prerequisites.adoc[tags=helm] +A Helm chart installs Flex Gateway, monitoring tools, and applications. +A minimum Helm version of 3.0.0 is required. Refer to <> for configuration options. + //- add chart repo and deploy flex via chart -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart-add;k8s-flex-helm-chart-deploy] +. Add a Helm repository named `flex-gateway` for your chart: ++ +[source,helm] +---- +helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm +---- ++ +The command either adds the repository or skips this process if a Helm repository with that name already exists on your machine: ++ +* If the repository is new, the command returns the following message: ++ +---- +"flex-gateway" has been added to your repositories +---- ++ +* If the repository already exists, the command returns the following message: ++ +---- +"flex-gateway" already exists with the same configuration, skipping +---- + +. Run `helm repo up`. ++ +The command returns the following message: ++ +---- +Hang tight while we grab the latest from your chart repositories... +...Successfully got an update from the "flex-gateway" chart repository +Update Complete. ⎈Happy Helming!⎈ +---- ++ +If you have more than one Helm repository on your machine, the message in your terminal window lists all of the repositories. +// PLEASE retain blank line before first step below + +. Run the Helm command for deploying your gateway in Connected Mode: ++ +[source,helm] +---- +helm -n gateway upgrade -i --create-namespace \ +ingress flex-gateway/flex-gateway \ +--set gateway.mode=connected \ +--set-file registration.content=registration.yaml +---- ++ +This command creates the `gateway` namespace and a release named `ingress` if they do not exist. You can use names of your choice for your namespace and release. The command syntax for the Helm repository and chart names is `/`. ++ +The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local Mode. ++ +When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must have the appropriate permissions to create a load balancer in your cloud. If the load balancer is not provisioned or has issues with the provisioning process, you must choose another type by changing the `service.type` property during the installation. ++ +NOTE: By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If there's no API deployed to your Flex Gateway instance, the readiness state is `false`. This isn’t an issue with custom readiness probe configurations. ++ +When successful, the command prints a message indicating an upgrade to your `ingress` release: ++ +---- +Release "ingress" does not exist. Installing it now. +NAME: ingress +LAST DEPLOYED: Mon Mar 20 21:36:19 2023 +NAMESPACE: gateway +STATUS: deployed +REVISION: 1 +TEST SUITE: None +---- ++ +The `REVISION` value increments the `ingress` release by `1` each time you run this command with the same namespace, repository, and chart names. For example, if you run the command a second time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date of that revision. +// do not add an empty new line here at end, please + //- for flex connected mode deployment only -include::partial$task-reg-run-flex-gateway.adoc[tags=gateway-connected] +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your new gateway in the UI. Notice that your gateway's current status is *Connected*. Refresh the page, if necessary. + +NOTE: After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI. Otherwise, the UI continues to list the gateway even if it is no longer running or connected. [[helm-options-k8s]] //helm config options -include::partial$task-reg-run-flex-gateway.adoc[tags=helm-chart-options] +=== Helm Chart Settings + +To modify the default Helm settings with new values, such as `resource` values for CPU and memory settings, see xref:flex-gateway-k8-change-helm-settings.adoc[]. For additional Helm chart configurations, see xref:flex-gateway-k8-management.adoc[]. + +Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings: + +* Open the *flex-gateway* page in https://artifacthub.io/packages/helm/flex-gateway/flex-gateway[ArtifactHUB^] +* Run `helm show values /` from a terminal window. ++ +.Example: +[source,kubernetes] +---- +helm show values flex-gateway/flex-gateway +---- ++ +The example returns _default_ values of a repository and chart with the same name. + +To view the Helm chart `README`, run `helm show readme /` from a terminal window. + +.Example: +[source,kubernetes] +---- +helm show readme flex-gateway/flex-gateway +---- // OPENSHIFT [[openshift]] // Register and run with a username and password in an OpenShift cluster //heading -include::partial$task-reg-run-flex-gateway.adoc[tags=user-openshift-heading] +== Register and Run with a Username and Password in an OpenShift Cluster //intro -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-intro-connected] +Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster and connect to Anypoint Platform. After deploying, use Runtime Manager to verify that the gateway is present and connected to Anypoint Platform. + //- cluster-level access when rbac enabled -include::partial$prerequisites.adoc[tags=rbac-permission-k8;rbac-role-openshift] +When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC), you must have cluster-level permissions to permit installation of custom resource definitions (CRDs) used by Flex Gateway. +In OpenShift, the `cluster-admin` role provides this level of access. + //- note (openshift command line procedures same as k8) -include::partial$task-reg-run-flex-gateway.adoc[tags=note-openshift-k8] +From the command line, OpenShift procedures match Kubernetes procedures. //- links to steps -include::partial$task-reg-run-flex-gateway.adoc[tags=links-to-openshift-reg-steps] +Complete the following steps: + +. <> +. <> +. <> + //- connected mode supplemental info for k8 and openshift -include::partial$task-reg-run-flex-gateway.adoc[tag=k8s-connected-intro] +In Connected Mode, Flex Gateway typically serves as an ingress or Edge API gateway that receives traffic from outside of the cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) services. + +Most management takes place within Anypoint Platform: + +* Deploy APIs to your cluster. +* Apply policies and other configurations. +* Create resources (_with the exception_ of Configuration and Service resources). + +In Connected Mode, resource creation through `kubectl apply` is possible but restricted to the following resource types: +Configuration, Service, Extension, and PolicyBinding of types `tls`, `tls-inbound`, and `tls-outbound`. For more info about resources, see xref:flex-local-configuration-reference-guide.adoc[]. [[options-openshift]] //sub collected info -include::partial$task-reg-run-flex-gateway.adoc[tags=sub-coll-info;user-replace-content;environment-replace-content;replace-content] +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster [[reg-openshift]] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading] +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-openshift-heading-intro] +You can register using one of the following container runtimes: + +// * <> +// * <> [[docker-openshift-container-reg]] .*Docker* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=docker-reg-command-heading-intro] +// ==== Docker +Run the following command to register using Docker: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;docker-reg-command;user-reg-command;environment-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg;disconnected-after-reg] +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--username= \ +--password= \ +--environment= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. + ==== [[podman-openshift-container-reg]] .*Podman* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=podman-reg-command-heading-intro] +// ==== Podman +Run the following command to register using Podman: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;podman-reg-command;user-reg-command;environment-reg-command;connected-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg;disconnected-after-reg] +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--username= \ +--password= \ +--environment= \ +--connected=true \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your gateway in the UI. Notice that your gateway's status is *Disconnected*. Refresh the page, if necessary. + ==== [[deploy-openshift]] //install helm chart section //- title -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-title] +=== Install Helm Chart into the Namespace + //- helm chart info -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart] -include::partial$prerequisites.adoc[tags=helm] +A Helm chart installs Flex Gateway, monitoring tools, and applications. +A minimum Helm version of 3.0.0 is required. Refer to <> for configuration options. + //- add chart repo and deploy flex via chart -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart-add;k8s-flex-helm-chart-deploy] +. Add a Helm repository named `flex-gateway` for your chart: ++ +[source,helm] +---- +helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm +---- ++ +The command either adds the repository or skips this process if a Helm repository with that name already exists on your machine: ++ +* If the repository is new, the command returns the following message: ++ +---- +"flex-gateway" has been added to your repositories +---- ++ +* If the repository already exists, the command returns the following message: ++ +---- +"flex-gateway" already exists with the same configuration, skipping +---- + +. Run `helm repo up`. ++ +The command returns the following message: ++ +---- +Hang tight while we grab the latest from your chart repositories... +...Successfully got an update from the "flex-gateway" chart repository +Update Complete. ⎈Happy Helming!⎈ +---- ++ +If you have more than one Helm repository on your machine, the message in your terminal window lists all of the repositories. +// PLEASE retain blank line before first step below + +. Run the Helm command for deploying your gateway in Connected Mode: ++ +[source,helm] +---- +helm -n gateway upgrade -i --create-namespace \ +ingress flex-gateway/flex-gateway \ +--set gateway.mode=connected \ +--set-file registration.content=registration.yaml +---- ++ +This command creates the `gateway` namespace and a release named `ingress` if they do not exist. You can use names of your choice for your namespace and release. The command syntax for the Helm repository and chart names is `/`. ++ +The command uses `--set gateway.mode=connected` because the default for the Helm chart is Local Mode. ++ +When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must have the appropriate permissions to create a load balancer in your cloud. If the load balancer is not provisioned or has issues with the provisioning process, you must choose another type by changing the `service.type` property during the installation. ++ +NOTE: By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If there's no API deployed to your Flex Gateway instance, the readiness state is `false`. This isn’t an issue with custom readiness probe configurations. ++ +When successful, the command prints a message indicating an upgrade to your `ingress` release: ++ +---- +Release "ingress" does not exist. Installing it now. +NAME: ingress +LAST DEPLOYED: Mon Mar 20 21:36:19 2023 +NAMESPACE: gateway +STATUS: deployed +REVISION: 1 +TEST SUITE: None +---- ++ +The `REVISION` value increments the `ingress` release by `1` each time you run this command with the same namespace, repository, and chart names. For example, if you run the command a second time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date of that revision. +// do not add an empty new line here at end, please + //- for flex connected mode deployment only -include::partial$task-reg-run-flex-gateway.adoc[tags=gateway-connected] +In Runtime Manager, click *← Flex Gateway* in the left navigation to find your new gateway in the UI. Notice that your gateway's current status is *Connected*. Refresh the page, if necessary. + +NOTE: After 30 days, a stopped or deleted gateway is removed from the Runtime Manager UI. Otherwise, the UI continues to list the gateway even if it is no longer running or connected. [[helm-options-openshift]] //helm config options -include::partial$task-reg-run-flex-gateway.adoc[tags=helm-chart-options] +=== Helm Chart Settings + +To modify the default Helm settings with new values, such as `resource` values for CPU and memory settings, see xref:flex-gateway-k8-change-helm-settings.adoc[]. For additional Helm chart configurations, see xref:flex-gateway-k8-management.adoc[]. + +Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings: + +* Open the *flex-gateway* page in https://artifacthub.io/packages/helm/flex-gateway/flex-gateway[ArtifactHUB^] +* Run `helm show values /` from a terminal window. ++ +.Example: +[source,kubernetes] +---- +helm show values flex-gateway/flex-gateway +---- ++ +The example returns _default_ values of a repository and chart with the same name. + +To view the Helm chart `README`, run `helm show readme /` from a terminal window. + +.Example: +[source,kubernetes] +---- +helm show readme flex-gateway/flex-gateway +---- == See Also diff --git a/gateway/1.9/modules/ROOT/pages/flex-conn-rep-run.adoc b/gateway/1.9/modules/ROOT/pages/flex-conn-rep-run.adoc index a7cc43059..0350c70ee 100644 --- a/gateway/1.9/modules/ROOT/pages/flex-conn-rep-run.adoc +++ b/gateway/1.9/modules/ROOT/pages/flex-conn-rep-run.adoc @@ -18,7 +18,9 @@ include::partial$task-rep-run-flex-gateway.adoc[tags=add-flex-intro] include::partial$task-rep-run-flex-gateway.adoc[tags=add-flex-rep-byb;add-flex-rep-byb-conn;add-flex-rep1] -include::partial$task-reg-run-flex-gateway.adoc[tags=create-config-folder-file;config-content;linux-start-commands] + + +include::partial$task-reg-run-flex-gateway.adoc[tags=linux-start-commands] include::partial$task-rep-run-flex-gateway.adoc[tags=add-flex-rep2] diff --git a/gateway/1.9/modules/ROOT/pages/flex-gateway-k8-getting-started.adoc b/gateway/1.9/modules/ROOT/pages/flex-gateway-k8-getting-started.adoc index 0baaf1ea2..25363b2f7 100644 --- a/gateway/1.9/modules/ROOT/pages/flex-gateway-k8-getting-started.adoc +++ b/gateway/1.9/modules/ROOT/pages/flex-gateway-k8-getting-started.adoc @@ -2,7 +2,7 @@ ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] -:reg-mode: Connected + Get started with Anypoint Flex Gateway in a Kubernetes cluster or an OpenShift cluster, which is based on Kubernetes. Set up a Flex Gateway deployment that connects to Anypoint Platform, and use the deployment to route traffic to your API. This guide covers the following high-level tasks: @@ -220,7 +220,7 @@ Confirm that your Kubernetes cluster is available by following the steps in <> +|<> +|<> +|<> +|=== [[prereqs]] // Prerequisites -include::partial$task-reg-run-flex-gateway.adoc[tags=prerequisites-heading;app-prerequisites;prerequisites;environment-prerequisites] +== Before You Begin + +Before registering Flex Gateway, you must complete the following tasks: + +* xref:access-management::connected-apps-developers.adoc#create-a-connected-app[Configure a Connected App] +** Include the following scopes: +*** Read Servers +*** Manage Servers +*** View Organization +** Save the *Id* and *Secret* of the Connected app you configure. + +* xref:flex-install.adoc[Install a Flex Gateway] +* Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint Platform admin +* Collect the following information from your Anypoint Platform instance: +** The *Organization ID* for the organization where you want to run Flex Gateway ++ +See xref:access-management::organization.adoc#find-your-organization-id[Find your Organization ID] for more information on how to find your Organization ID. + +** The *Environment ID* for the environment where you want to run Flex Gateway ++ +See xref:api-manager::latest-overview-concept.adoc#what-api-manager-looks-like[What API Manager Looks Like] +for more information on how to find your Environment ID. [[linux]] // Register and run with a connected app as a Linux service -include::partial$task-reg-run-flex-gateway.adoc[tags=app-linux-heading] -include::partial$prerequisites.adoc[tag=intro] +== Register and Run with a Connected App as a Linux Service +Flex Gateway runs on the following Long Term Support (LTS) versions of Linux: * {empty} -include::partial$prerequisites.adoc[tag=amazon-linux] +Amazon Linux 2023 * {empty} -include::partial$prerequisites.adoc[tag=centos] +CentOS 8 * {empty} -include::partial$prerequisites.adoc[tag=debian] +Debian (Bullseye, Bookworm) * {empty} -include::partial$prerequisites.adoc[tag=red-hat] +Red Hat Enterprise Linux (9) * {empty} -include::partial$prerequisites.adoc[tag=red-hat-ibm] +Red Hat Enterprise Linux (9) on IBM Power (ppc64le) * {empty} -include::partial$prerequisites.adoc[tag=suse] +SUSE Linux Enterprise (SLES 15 SP3) * {empty} -include::partial$prerequisites.adoc[tag=suse-ibm] +SUSE Linux Enterprise (SLES 15 SP3) on IBM Power (ppc64le) * {empty} -include::partial$prerequisites.adoc[tag=ubuntu] +Ubuntu (Focal, Jammy) + +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--client-id` = the Id for the Connected App you configured in Access Management +* `--client-secret` = the Secret for the Connected App you configured in Access Management +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster + +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +[source,ssh,subs=attributes+] +---- +flexctl registration create \ +--client-id= \ +--client-secret= \ +--environment= \ +--organization= \ +--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-intro;sub-coll-info;app-replace-content;environment-replace-content;replace-content;reg-command-heading;reg-command-1;linux-reg-command;app-reg-command;environment-reg-command;organization-reg-command;output-reg-command-linux;reg-command-2;after-reg;linux-after-reg;create-config-folder-file;config-content;linux-start-commands] +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + + + +=== Start Commands + +Start Flex Gateway with the following command: + +[source,ssh] +---- +sudo systemctl start flex-gateway +---- + +Verify that the Flex Gateway service is running successfully: + +[source,ssh] +---- +systemctl list-units flex-gateway* +---- + +If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running. + +[source,text] +---- + UNIT LOAD ACTIVE SUB DESCRIPTION + flex-gateway.service loaded active running Application +---- [[container]] -include::partial$task-reg-run-flex-gateway.adoc[tags=app-container-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=table-containers-logos-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=table-containers-logos-links] +== Register and Run with a Connected App in a Container +You can register and run Flex Gateway for use in one of the following containers: +[cols="1a,1a"] +|=== +|image:install-docker-logo.png[15%,15%,xref="#docker"] +|image:install-podman-logo.png[12%,12%,xref="#podman"] + +|<> +|<> +|=== [[docker]] // Register and run with a connected app in a Docker container -include::partial$task-reg-run-flex-gateway.adoc[tags=app-docker-heading;reg-command-intro;sub-coll-info-container;app-replace-content;environment-replace-content;replace-content;reg-command-heading-container;docker-create-directory-note;reg-command-1;docker-reg-command;app-reg-command;environment-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;after-reg-2;start-command-local-intro;start-command-local;start-command-local-valid] +=== Register and Run with a Connected App in a Docker Container +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +==== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--client-id` = the Id for the Connected App you configured in Access Management +* `--client-secret` = the Secret for the Connected App you configured in Access Management +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster + +==== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +IMPORTANT: Create a new directory called `flex-registration` (or similar) and then run the registration command in this new directory. The command creates registration files in this location. + +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--client-id= \ +--client-secret= \ +--environment= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +==== Start Command + +Run the following start command in the same directory where you ran the registration command: + +[source,ssh,subs=attributes+] +---- +docker run --rm \ +-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \ +-p 8080:8080 \ +mulesoft/flex-gateway +---- +NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. + +The output logs should include this line: + +[source,ssh] +---- +[flex-gateway-envoy][info] all dependencies initialized. starting workers +---- // PODMAN [[podman]] // Register and run with a connected app in a Podman container -include::partial$task-reg-run-flex-gateway.adoc[tags=app-podman-heading;reg-command-intro;sub-coll-info-container;app-replace-content;environment-replace-content;replace-content;reg-command-heading-container;docker-create-directory-note;reg-command-1;podman-reg-command;app-reg-command;environment-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;after-reg-2;start-command-local-intro;podman-start-command-local;start-command-local-valid] +=== Register and Run with a Connected App in a Podman Container +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +==== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--client-id` = the Id for the Connected App you configured in Access Management +* `--client-secret` = the Secret for the Connected App you configured in Access Management +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster + +==== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +IMPORTANT: Create a new directory called `flex-registration` (or similar) and then run the registration command in this new directory. The command creates registration files in this location. + +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--client-id= \ +--client-secret= \ +--environment= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +==== Start Command + +Run the following start command in the same directory where you ran the registration command: + +[source,ssh,subs=attributes+] +---- +podman run --rm \ +-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \ +-p 8080:8080 \ +docker.io/mulesoft/flex-gateway +---- +NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. + +The output logs should include this line: + +[source,ssh] +---- +[flex-gateway-envoy][info] all dependencies initialized. starting workers +---- // KUBERNETES [[kubernetes]] -// Register and run with a connected app in a kubernetes cluster -//heading -include::partial$task-reg-run-flex-gateway.adoc[tags=app-k8s-heading] +// Register and run with a connected app in a Kubernetes cluster + +//intro + +== Register and Run with a Connected App in a Kubernetes Cluster + // - task overview -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-intro-local] +Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster. + // - cluster-level access when rbac enabled -include::partial$prerequisites.adoc[tags=rbac-permission-k8] +When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC), you must have cluster-level permissions to permit installation of custom resource definitions (CRDs) used by Flex Gateway. + //- links to steps -include::partial$task-reg-run-flex-gateway.adoc[tags=links-to-k8s-reg-steps] +Complete the following steps: + +. <> +. <> +. <> + // - local mode overview for k8 and openshift (supplements general info elsewhere) -include::partial$task-reg-run-flex-gateway.adoc[tag=k8s-local-intro] +In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic. + +When using this mode, you must know what resources to create and apply, and use `kubectl apply` to deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to your gateway. + +Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway routing rules. You provide this configuration through a YAML file. The file supports other properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex Gateway manages `Ingress` resources, see xref:flex-gateway-k8-ingress-class.adoc[]. [[options-k8s]] //sub collected info -include::partial$task-reg-run-flex-gateway.adoc[tags=sub-coll-info;app-replace-content;environment-replace-content;replace-content] +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--client-id` = the Id for the Connected App you configured in Access Management +* `--client-secret` = the Secret for the Connected App you configured in Access Management +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster [[reg-k8s]] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading-intro] +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +You can register using one of the following container runtimes: + +// * <> +// * <> [[docker-container-reg]] .*Docker* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=docker-reg-command-heading-intro] +// ==== Docker +Run the following command to register using Docker: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;docker-reg-command;app-reg-command;environment-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg] +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--client-id= \ +--client-secret= \ +--environment= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + ==== [[podman-container-reg]] .*Podman* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=podman-reg-command-heading-intro] +// ==== Podman +Run the following command to register using Podman: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;podman-reg-command;app-reg-command;environment-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg] +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--client-id= \ +--client-secret= \ +--environment= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + ==== [[deploy-k8s]] -//install helm chart +//install helm chart section //- title -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-title] + +=== Install Helm Chart into the Namespace + //- helm chart info -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart] -include::partial$prerequisites.adoc[tags=helm] +A Helm chart installs Flex Gateway, monitoring tools, and applications. +A minimum Helm version of 3.0.0 is required. Refer to <> for configuration options. + //- add chart repo and deploy flex via chart -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart-add;k8s-flex-helm-chart-deploy-local] + +. Add a Helm repository named `flex-gateway` for your chart: ++ +[source,helm] +---- +helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm +---- ++ +The command either adds the repository or skips this process if a Helm repository with that name already exists on your machine: ++ +* If the repository is new, the command returns the following message: ++ +---- +"flex-gateway" has been added to your repositories +---- ++ +* If the repository already exists, the command returns the following message: ++ +---- +"flex-gateway" already exists with the same configuration, skipping +---- + +. Run `helm repo up`. ++ +The command returns the following message: ++ +---- +Hang tight while we grab the latest from your chart repositories... +...Successfully got an update from the "flex-gateway" chart repository +Update Complete. ⎈Happy Helming!⎈ +---- ++ +If you have more than one Helm repository on your machine, the message in your terminal window lists all of the repositories. +// PLEASE retain blank line before first step below + +. Run the Helm command for deploying your gateway in Local Mode: ++ +[source,helm] +---- +helm -n gateway upgrade -i --create-namespace \ +ingress flex-gateway/flex-gateway \ +--set-file registration.content=registration.yaml +---- ++ +This command creates the `gateway` namespace and a release named `ingress` if they do not exist. You can use names of your choice for your namespace and release. The command syntax for the Helm repository and chart names is `/`. ++ +When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must have the appropriate permissions to create a load balancer in your cloud. If the load balancer is not provisioned or has issues with the provisioning process, you must choose another type by changing the `service.type` property during the installation. ++ +NOTE: By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If there's no API deployed to your Flex Gateway instance, the readiness state is `false`. This isn’t an issue with custom readiness probe configurations. ++ +When successful, the command prints a message indicating an upgrade to your `ingress` release: ++ +---- +Release "ingress" does not exist. Installing it now. +NAME: ingress +LAST DEPLOYED: Mon Mar 20 21:36:19 2023 +NAMESPACE: gateway +STATUS: deployed +REVISION: 1 +TEST SUITE: None +---- ++ +The `REVISION` value increments the `ingress` release by `1` each time you run this command with the same namespace, repository, and chart names. For example, if you run the command a second time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date of that revision. +// do not add an empty new line here at end, please [[helm-options-k8s]] //helm config options -include::partial$task-reg-run-flex-gateway.adoc[tags=helm-chart-options] +=== Helm Chart Settings + +To modify the default Helm settings with new values, such as `resource` values for CPU and memory settings, see xref:flex-gateway-k8-change-helm-settings.adoc[]. For additional Helm chart configurations, see xref:flex-gateway-k8-management.adoc[]. + +Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings: + +* Open the *flex-gateway* page in https://artifacthub.io/packages/helm/flex-gateway/flex-gateway[ArtifactHUB^] +* Run `helm show values /` from a terminal window. ++ +.Example: +[source,kubernetes] +---- +helm show values flex-gateway/flex-gateway +---- ++ +The example returns _default_ values of a repository and chart with the same name. + +To view the Helm chart `README`, run `helm show readme /` from a terminal window. + +.Example: +[source,kubernetes] +---- +helm show readme flex-gateway/flex-gateway +---- // OPENSHIFT [[openshift]] // Register and run with a connected app in an OpenShift cluster //heading -include::partial$task-reg-run-flex-gateway.adoc[tags=app-openshift-heading] +== Register and Run with a Connected App in an OpenShift Cluster //intro -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-intro-local] +Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster. + //- cluster-level access when rbac enabled, as for OpenShift -include::partial$prerequisites.adoc[tags=rbac-permission-k8;rbac-role-openshift] +When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC), you must have cluster-level permissions to permit installation of custom resource definitions (CRDs) used by Flex Gateway. +In OpenShift, the `cluster-admin` role provides this level of access. + //- note (openshift command line procedures same as k8) -include::partial$task-reg-run-flex-gateway.adoc[tags=note-openshift-k8] +From the command line, OpenShift procedures match Kubernetes procedures. //- links to steps -include::partial$task-reg-run-flex-gateway.adoc[tags=links-to-openshift-reg-steps] +Complete the following steps: + +. <> +. <> +. <> + //- local mode supplemental info for k8 and openshift -include::partial$task-reg-run-flex-gateway.adoc[tag=k8s-local-intro] +In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic. + +When using this mode, you must know what resources to create and apply, and use `kubectl apply` to deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to your gateway. + +Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway routing rules. You provide this configuration through a YAML file. The file supports other properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex Gateway manages `Ingress` resources, see xref:flex-gateway-k8-ingress-class.adoc[]. [[options-openshift]] //sub collected info -include::partial$task-reg-run-flex-gateway.adoc[tags=sub-coll-info;app-replace-content;environment-replace-content;replace-content] +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--client-id` = the Id for the Connected App you configured in Access Management +* `--client-secret` = the Secret for the Connected App you configured in Access Management +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster [[reg-openshift]] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading] +=== Register Flex Gateway -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-openshift-heading-intro] +Register your Flex Gateway instance using the data that you gathered for the command options. + +You can register using one of the following container runtimes: + +// * <> +// * <> [[docker-openshift-container-reg]] .*Docker* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=docker-reg-command-heading-intro] +// ==== Docker +Run the following command to register using Docker: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;docker-reg-command;app-reg-command;environment-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg] +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--client-id= \ +--client-secret= \ +--environment= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + ==== [[podman-openshift-container-reg]] .*Podman* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=podman-reg-command-heading-intro] +// ==== Podman +Run the following command to register using Podman: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;podman-reg-command;app-reg-command;environment-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg] +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--client-id= \ +--client-secret= \ +--environment= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + ==== [[deploy-openshift]] //install helm chart //- title -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-title] +=== Install Helm Chart into the Namespace + //- helm chart info -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart] -include::partial$prerequisites.adoc[tags=helm] +A Helm chart installs Flex Gateway, monitoring tools, and applications. +A minimum Helm version of 3.0.0 is required. Refer to <> for configuration options. //- add chart repo and deploy flex via chart -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart-add;k8s-flex-helm-chart-deploy-local] + +. Add a Helm repository named `flex-gateway` for your chart: ++ +[source,helm] +---- +helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm +---- ++ +The command either adds the repository or skips this process if a Helm repository with that name already exists on your machine: ++ +* If the repository is new, the command returns the following message: ++ +---- +"flex-gateway" has been added to your repositories +---- ++ +* If the repository already exists, the command returns the following message: ++ +---- +"flex-gateway" already exists with the same configuration, skipping +---- + +. Run `helm repo up`. ++ +The command returns the following message: ++ +---- +Hang tight while we grab the latest from your chart repositories... +...Successfully got an update from the "flex-gateway" chart repository +Update Complete. ⎈Happy Helming!⎈ +---- ++ +If you have more than one Helm repository on your machine, the message in your terminal window lists all of the repositories. +// PLEASE retain blank line before first step below + +. Run the Helm command for deploying your gateway in Local Mode: ++ +[source,helm] +---- +helm -n gateway upgrade -i --create-namespace \ +ingress flex-gateway/flex-gateway \ +--set-file registration.content=registration.yaml +---- ++ +This command creates the `gateway` namespace and a release named `ingress` if they do not exist. You can use names of your choice for your namespace and release. The command syntax for the Helm repository and chart names is `/`. ++ +When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must have the appropriate permissions to create a load balancer in your cloud. If the load balancer is not provisioned or has issues with the provisioning process, you must choose another type by changing the `service.type` property during the installation. ++ +NOTE: By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If there's no API deployed to your Flex Gateway instance, the readiness state is `false`. This isn’t an issue with custom readiness probe configurations. ++ +When successful, the command prints a message indicating an upgrade to your `ingress` release: ++ +---- +Release "ingress" does not exist. Installing it now. +NAME: ingress +LAST DEPLOYED: Mon Mar 20 21:36:19 2023 +NAMESPACE: gateway +STATUS: deployed +REVISION: 1 +TEST SUITE: None +---- ++ +The `REVISION` value increments the `ingress` release by `1` each time you run this command with the same namespace, repository, and chart names. For example, if you run the command a second time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date of that revision. +// do not add an empty new line here at end, please [[helm-options-openshift]] //helm config options -include::partial$task-reg-run-flex-gateway.adoc[tags=helm-chart-options] +=== Helm Chart Settings + +To modify the default Helm settings with new values, such as `resource` values for CPU and memory settings, see xref:flex-gateway-k8-change-helm-settings.adoc[]. For additional Helm chart configurations, see xref:flex-gateway-k8-management.adoc[]. + +Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings: + +* Open the *flex-gateway* page in https://artifacthub.io/packages/helm/flex-gateway/flex-gateway[ArtifactHUB^] +* Run `helm show values /` from a terminal window. ++ +.Example: +[source,kubernetes] +---- +helm show values flex-gateway/flex-gateway +---- ++ +The example returns _default_ values of a repository and chart with the same name. + +To view the Helm chart `README`, run `helm show readme /` from a terminal window. + +.Example: +[source,kubernetes] +---- +helm show readme flex-gateway/flex-gateway +---- == See Also diff --git a/gateway/1.9/modules/ROOT/pages/flex-local-reg-run-token.adoc b/gateway/1.9/modules/ROOT/pages/flex-local-reg-run-token.adoc index 3ffb16228..86e547e62 100644 --- a/gateway/1.9/modules/ROOT/pages/flex-local-reg-run-token.adoc +++ b/gateway/1.9/modules/ROOT/pages/flex-local-reg-run-token.adoc @@ -3,177 +3,728 @@ ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] :imagesdir: ../assets/images -:reg-mode: Local + //table with tech logos and links (linux, docker, k8, openshift) -include::partial$task-reg-run-flex-gateway.adoc[tags=table-logos-links] +[cols="1a,1a,1a,1a"] +|=== +|image:install-linux-logo.png[20%,20%,xref="#linux"] +|image:install-container-logo.png[25%,25%,xref="#container"] +|image:install-kubernetes-logo.png[20%,20%,xref="#kubernetes"] +|image:install-openshift-logo.png[20%,20%,xref="#openshift"] + +|<> +|<> +|<> +|<> +|=== [[prereqs]] // Prerequisites -include::partial$task-reg-run-flex-gateway.adoc[tags=prerequisites-heading;prerequisites;token-prerequisites] +== Before You Begin + +Before registering Flex Gateway, you must complete the following tasks: + +* xref:flex-install.adoc[Install a Flex Gateway] +* Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint Platform admin +* Collect the following information from your Anypoint Platform instance: +** The *Organization ID* for the organization where you want to run Flex Gateway ++ +See xref:access-management::organization.adoc#find-your-organization-id[Find your Organization ID] for more information on how to find your Organization ID. + +** The registration *token* for the environment in Anypoint Platform where you want to run Flex Gateway ++ +Navigate to Runtime Manager, select *Flex Gateway* in the left navigation, and click *Add Gateway* +to generate set of instructions that includes a command block with the registration token. [[linux]] // Register and run with a username and password as a Linux service -include::partial$task-reg-run-flex-gateway.adoc[tags=token-linux-heading] -include::partial$prerequisites.adoc[tag=intro] +== Register and Run with a Token as a Linux Service +Flex Gateway runs on the following Long Term Support (LTS) versions of Linux: * {empty} -include::partial$prerequisites.adoc[tag=amazon-linux] +Amazon Linux 2023 * {empty} -include::partial$prerequisites.adoc[tag=centos] +CentOS 8 * {empty} -include::partial$prerequisites.adoc[tag=debian] +Debian (Bullseye, Bookworm) * {empty} -include::partial$prerequisites.adoc[tag=red-hat] +Red Hat Enterprise Linux (9) * {empty} -include::partial$prerequisites.adoc[tag=red-hat-ibm] +Red Hat Enterprise Linux (9) on IBM Power (ppc64le) * {empty} -include::partial$prerequisites.adoc[tag=suse] +SUSE Linux Enterprise (SLES 15 SP3) * {empty} -include::partial$prerequisites.adoc[tag=suse-ibm] +SUSE Linux Enterprise (SLES 15 SP3) on IBM Power (ppc64le) * {empty} -include::partial$prerequisites.adoc[tag=ubuntu] +Ubuntu (Focal, Jammy) + +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--token` = the registration token for your environment in Anypoint Platform +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster + +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. +[source,ssh,subs=attributes+] +---- +flexctl registration create \ +--token= \ +--organization= \ +--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-intro;sub-coll-info;token-replace-content;replace-content;reg-command-heading;reg-command-1;linux-reg-command;token-reg-command;organization-reg-command;output-reg-command-linux;reg-command-2;after-reg;linux-after-reg;create-config-folder-file;config-content;linux-start-commands] +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + + + +=== Start Commands + +Start Flex Gateway with the following command: + +[source,ssh] +---- +sudo systemctl start flex-gateway +---- + +Verify that the Flex Gateway service is running successfully: + +[source,ssh] +---- +systemctl list-units flex-gateway* +---- + +If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running. + +[source,text] +---- + UNIT LOAD ACTIVE SUB DESCRIPTION + flex-gateway.service loaded active running Application +---- [[container]] -include::partial$task-reg-run-flex-gateway.adoc[tags=token-container-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=table-containers-logos-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=table-containers-logos-links] +== Register and Run with a Token in a Container +You can register and run Flex Gateway for use in one of the following containers: +[cols="1a,1a"] +|=== +|image:install-docker-logo.png[15%,15%,xref="#docker"] +|image:install-podman-logo.png[12%,12%,xref="#podman"] + +|<> +|<> +|=== [[docker]] // Register and run with a token in a Docker container -include::partial$task-reg-run-flex-gateway.adoc[tags=token-docker-heading;reg-command-intro;sub-coll-info-container;token-replace-content;replace-content;reg-command-heading-container;docker-create-directory-note;reg-command-1;docker-reg-command;token-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;after-reg-2;start-command-local-intro;start-command-local;start-command-local-valid] +=== Register and Run with a Token in a Docker Container +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +==== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--token` = the registration token for your environment in Anypoint Platform +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster + +==== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +IMPORTANT: Create a new directory called `flex-registration` (or similar) and then run the registration command in this new directory. The command creates registration files in this location. +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--token= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +==== Start Command + +Run the following start command in the same directory where you ran the registration command: +[source,ssh,subs=attributes+] +---- +docker run --rm \ +-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \ +-p 8080:8080 \ +mulesoft/flex-gateway +---- +NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. + +The output logs should include this line: + +[source,ssh] +---- +[flex-gateway-envoy][info] all dependencies initialized. starting workers +---- // PODMAN [[podman]] // Register and run with a token in a Podman container -include::partial$task-reg-run-flex-gateway.adoc[tags=token-podman-heading;reg-command-intro;sub-coll-info-container;token-replace-content;replace-content;reg-command-heading-container;docker-create-directory-note;reg-command-1;podman-reg-command;token-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;after-reg-2;start-command-local-intro;podman-start-command-local;start-command-local-valid] +=== Register and Run with a Token in a Podman Container +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +==== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--token` = the registration token for your environment in Anypoint Platform +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster + +==== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +IMPORTANT: Create a new directory called `flex-registration` (or similar) and then run the registration command in this new directory. The command creates registration files in this location. +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--token= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +==== Start Command + +Run the following start command in the same directory where you ran the registration command: +[source,ssh,subs=attributes+] +---- +podman run --rm \ +-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \ +-p 8080:8080 \ +docker.io/mulesoft/flex-gateway +---- +NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. + +The output logs should include this line: + +[source,ssh] +---- +[flex-gateway-envoy][info] all dependencies initialized. starting workers +---- // KUBERNETES [[kubernetes]] // Register and run with a token in a kubernetes cluster //heading -include::partial$task-reg-run-flex-gateway.adoc[tags=token-k8s-heading] +== Register and Run with a Token in a Kubernetes Cluster //intro -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-intro-local] +Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster. + //- cluster-level access when rbac enabled, as for OpenShift -include::partial$prerequisites.adoc[tags=rbac-permission-k8] +When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC), you must have cluster-level permissions to permit installation of custom resource definitions (CRDs) used by Flex Gateway. + //- links to steps -include::partial$task-reg-run-flex-gateway.adoc[tags=links-to-k8s-reg-steps] +Complete the following steps: + +. <> +. <> +. <> + //- local mode supplemental info for k8 and openshift -include::partial$task-reg-run-flex-gateway.adoc[tag=k8s-local-intro] +In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic. + +When using this mode, you must know what resources to create and apply, and use `kubectl apply` to deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to your gateway. + +Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway routing rules. You provide this configuration through a YAML file. The file supports other properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex Gateway manages `Ingress` resources, see xref:flex-gateway-k8-ingress-class.adoc[]. [[options-k8s]] //sub collected info -include::partial$task-reg-run-flex-gateway.adoc[tags=sub-coll-info;token-replace-content;replace-content] +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--token` = the registration token for your environment in Anypoint Platform +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster [[reg-k8s]] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading-intro] +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +You can register using one of the following container runtimes: + +// * <> +// * <> [[docker-container-reg]] .*Docker* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=docker-reg-command-heading-intro] +// ==== Docker +Run the following command to register using Docker: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;docker-reg-command;token-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg] +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--token= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + ==== [[podman-container-reg]] .*Podman* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=podman-reg-command-heading-intro] +// ==== Podman +Run the following command to register using Podman: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;podman-reg-command;token-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg] +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--token= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + ==== [[deploy-k8s]] //install helm chart //- title -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-title] +=== Install Helm Chart into the Namespace + //- helm chart info -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart] -include::partial$prerequisites.adoc[tags=helm] +A Helm chart installs Flex Gateway, monitoring tools, and applications. +A minimum Helm version of 3.0.0 is required. Refer to <> for configuration options. + //- add chart repo and deploy flex via chart -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart-add;k8s-flex-helm-chart-deploy-local] +. Add a Helm repository named `flex-gateway` for your chart: ++ +[source,helm] +---- +helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm +---- ++ +The command either adds the repository or skips this process if a Helm repository with that name already exists on your machine: ++ +* If the repository is new, the command returns the following message: ++ +---- +"flex-gateway" has been added to your repositories +---- ++ +* If the repository already exists, the command returns the following message: ++ +---- +"flex-gateway" already exists with the same configuration, skipping +---- + +. Run `helm repo up`. ++ +The command returns the following message: ++ +---- +Hang tight while we grab the latest from your chart repositories... +...Successfully got an update from the "flex-gateway" chart repository +Update Complete. ⎈Happy Helming!⎈ +---- ++ +If you have more than one Helm repository on your machine, the message in your terminal window lists all of the repositories. +// PLEASE retain blank line before first step below + +. Run the Helm command for deploying your gateway in Local Mode: ++ +[source,helm] +---- +helm -n gateway upgrade -i --create-namespace \ +ingress flex-gateway/flex-gateway \ +--set-file registration.content=registration.yaml +---- ++ +This command creates the `gateway` namespace and a release named `ingress` if they do not exist. You can use names of your choice for your namespace and release. The command syntax for the Helm repository and chart names is `/`. ++ +When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must have the appropriate permissions to create a load balancer in your cloud. If the load balancer is not provisioned or has issues with the provisioning process, you must choose another type by changing the `service.type` property during the installation. ++ +NOTE: By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If there's no API deployed to your Flex Gateway instance, the readiness state is `false`. This isn’t an issue with custom readiness probe configurations. ++ +When successful, the command prints a message indicating an upgrade to your `ingress` release: ++ +---- +Release "ingress" does not exist. Installing it now. +NAME: ingress +LAST DEPLOYED: Mon Mar 20 21:36:19 2023 +NAMESPACE: gateway +STATUS: deployed +REVISION: 1 +TEST SUITE: None +---- ++ +The `REVISION` value increments the `ingress` release by `1` each time you run this command with the same namespace, repository, and chart names. For example, if you run the command a second time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date of that revision. +// do not add an empty new line here at end, please [[helm-options-k8s]] //helm config options -include::partial$task-reg-run-flex-gateway.adoc[tags=helm-chart-options] +=== Helm Chart Settings + +To modify the default Helm settings with new values, such as `resource` values for CPU and memory settings, see xref:flex-gateway-k8-change-helm-settings.adoc[]. For additional Helm chart configurations, see xref:flex-gateway-k8-management.adoc[]. + +Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings: + +* Open the *flex-gateway* page in https://artifacthub.io/packages/helm/flex-gateway/flex-gateway[ArtifactHUB^] +* Run `helm show values /` from a terminal window. ++ +.Example: +[source,kubernetes] +---- +helm show values flex-gateway/flex-gateway +---- ++ +The example returns _default_ values of a repository and chart with the same name. + +To view the Helm chart `README`, run `helm show readme /` from a terminal window. + +.Example: +[source,kubernetes] +---- +helm show readme flex-gateway/flex-gateway +---- // OPENSHIFT [[openshift]] // Register and run with a token in an OpenShift cluster //heading -include::partial$task-reg-run-flex-gateway.adoc[tags=token-openshift-heading] +== Register and Run with a Token in an OpenShift Cluster //intro -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-intro-local] +Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster. + //- cluster-level access when rbac enabled, as for OpenShift -include::partial$prerequisites.adoc[tags=rbac-permission-k8;rbac-role-openshift] +When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC), you must have cluster-level permissions to permit installation of custom resource definitions (CRDs) used by Flex Gateway. +In OpenShift, the `cluster-admin` role provides this level of access. + //- note (openshift command line procedures same as k8) -include::partial$task-reg-run-flex-gateway.adoc[tags=note-openshift-k8] +From the command line, OpenShift procedures match Kubernetes procedures. //- links to steps -include::partial$task-reg-run-flex-gateway.adoc[tags=links-to-openshift-reg-steps] +Complete the following steps: + +. <> +. <> +. <> + //- local mode supplemental info for k8 and openshift -include::partial$task-reg-run-flex-gateway.adoc[tag=k8s-local-intro] +In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic. + +When using this mode, you must know what resources to create and apply, and use `kubectl apply` to deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to your gateway. + +Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway routing rules. You provide this configuration through a YAML file. The file supports other properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex Gateway manages `Ingress` resources, see xref:flex-gateway-k8-ingress-class.adoc[]. [[options-openshift]] //sub collected info -include::partial$task-reg-run-flex-gateway.adoc[tags=sub-coll-info;token-replace-content;replace-content] +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--token` = the registration token for your environment in Anypoint Platform +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster [[reg-openshift]] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading] +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +You can register using one of the following container runtimes: -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-openshift-heading-intro] +// * <> +// * <> [[docker-openshift-container-reg]] .*Docker* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=docker-reg-command-heading-intro] +// ==== Docker +Run the following command to register using Docker: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;docker-reg-command;token-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg] +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--token= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + ==== [[podman-openshift-container-reg]] .*Podman* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=podman-reg-command-heading-intro] +// ==== Podman +Run the following command to register using Podman: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;podman-reg-command;token-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg] +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--token= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + ==== [[deploy-openshift]] //install helm chart //- title -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-title] +=== Install Helm Chart into the Namespace + //- helm chart info -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart] -include::partial$prerequisites.adoc[tags=helm] +A Helm chart installs Flex Gateway, monitoring tools, and applications. +A minimum Helm version of 3.0.0 is required. Refer to <> for configuration options. + //- add chart repo and deploy flex via chart -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart-add;k8s-flex-helm-chart-deploy-local] +. Add a Helm repository named `flex-gateway` for your chart: ++ +[source,helm] +---- +helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm +---- ++ +The command either adds the repository or skips this process if a Helm repository with that name already exists on your machine: ++ +* If the repository is new, the command returns the following message: ++ +---- +"flex-gateway" has been added to your repositories +---- ++ +* If the repository already exists, the command returns the following message: ++ +---- +"flex-gateway" already exists with the same configuration, skipping +---- + +. Run `helm repo up`. ++ +The command returns the following message: ++ +---- +Hang tight while we grab the latest from your chart repositories... +...Successfully got an update from the "flex-gateway" chart repository +Update Complete. ⎈Happy Helming!⎈ +---- ++ +If you have more than one Helm repository on your machine, the message in your terminal window lists all of the repositories. +// PLEASE retain blank line before first step below + +. Run the Helm command for deploying your gateway in Local Mode: ++ +[source,helm] +---- +helm -n gateway upgrade -i --create-namespace \ +ingress flex-gateway/flex-gateway \ +--set-file registration.content=registration.yaml +---- ++ +This command creates the `gateway` namespace and a release named `ingress` if they do not exist. You can use names of your choice for your namespace and release. The command syntax for the Helm repository and chart names is `/`. ++ +When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must have the appropriate permissions to create a load balancer in your cloud. If the load balancer is not provisioned or has issues with the provisioning process, you must choose another type by changing the `service.type` property during the installation. ++ +NOTE: By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If there's no API deployed to your Flex Gateway instance, the readiness state is `false`. This isn’t an issue with custom readiness probe configurations. ++ +When successful, the command prints a message indicating an upgrade to your `ingress` release: ++ +---- +Release "ingress" does not exist. Installing it now. +NAME: ingress +LAST DEPLOYED: Mon Mar 20 21:36:19 2023 +NAMESPACE: gateway +STATUS: deployed +REVISION: 1 +TEST SUITE: None +---- ++ +The `REVISION` value increments the `ingress` release by `1` each time you run this command with the same namespace, repository, and chart names. For example, if you run the command a second time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date of that revision. +// do not add an empty new line here at end, please [[helm-options-openshift]] //helm config options -include::partial$task-reg-run-flex-gateway.adoc[tags=helm-chart-options] +=== Helm Chart Settings + +To modify the default Helm settings with new values, such as `resource` values for CPU and memory settings, see xref:flex-gateway-k8-change-helm-settings.adoc[]. For additional Helm chart configurations, see xref:flex-gateway-k8-management.adoc[]. + +Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings: + +* Open the *flex-gateway* page in https://artifacthub.io/packages/helm/flex-gateway/flex-gateway[ArtifactHUB^] +* Run `helm show values /` from a terminal window. ++ +.Example: +[source,kubernetes] +---- +helm show values flex-gateway/flex-gateway +---- ++ +The example returns _default_ values of a repository and chart with the same name. + +To view the Helm chart `README`, run `helm show readme /` from a terminal window. + +.Example: +[source,kubernetes] +---- +helm show readme flex-gateway/flex-gateway +---- == See Also diff --git a/gateway/1.9/modules/ROOT/pages/flex-local-reg-run-up.adoc b/gateway/1.9/modules/ROOT/pages/flex-local-reg-run-up.adoc index 2eab51d7d..97112a75b 100644 --- a/gateway/1.9/modules/ROOT/pages/flex-local-reg-run-up.adoc +++ b/gateway/1.9/modules/ROOT/pages/flex-local-reg-run-up.adoc @@ -3,177 +3,753 @@ ifndef::env-site,env-github[] include::_attributes.adoc[] endif::[] :imagesdir: ../assets/images -:reg-mode: Local //table with tech logos and links (linux, docker, k8, openshift) -include::partial$task-reg-run-flex-gateway.adoc[tags=table-logos-links] +[cols="1a,1a,1a,1a"] +|=== +|image:install-linux-logo.png[20%,20%,xref="#linux"] +|image:install-container-logo.png[25%,25%,xref="#container"] +|image:install-kubernetes-logo.png[20%,20%,xref="#kubernetes"] +|image:install-openshift-logo.png[20%,20%,xref="#openshift"] + +|<> +|<> +|<> +|<> +|=== [[prereqs]] // Prerequisites -include::partial$task-reg-run-flex-gateway.adoc[tags=prerequisites-heading;prerequisites;environment-prerequisites;user-prerequisites] +== Before You Begin + +Before registering Flex Gateway, you must complete the following tasks: + +* xref:flex-install.adoc[Install a Flex Gateway] +* Request _Manage Servers_ and _Read Servers_ permissions in Runtime Manager from your Anypoint Platform admin +* Collect the following information from your Anypoint Platform instance: +** The *Organization ID* for the organization where you want to run Flex Gateway ++ +See xref:access-management::organization.adoc#find-your-organization-id[Find your Organization ID] for more information on how to find your Organization ID. + +** The *Environment ID* for the environment where you want to run Flex Gateway ++ +See xref:api-manager::latest-overview-concept.adoc#what-api-manager-looks-like[What API Manager Looks Like] +for more information on how to find your Environment ID. + +** The *Username* and *Password* of a user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager [[linux]] // Register and run with a username and password as a Linux service -include::partial$task-reg-run-flex-gateway.adoc[tags=user-linux-heading] -include::partial$prerequisites.adoc[tag=intro] +== Register and Run with a Username and Password as a Linux Service +Flex Gateway runs on the following Long Term Support (LTS) versions of Linux: * {empty} -include::partial$prerequisites.adoc[tag=amazon-linux] +Amazon Linux 2023 * {empty} -include::partial$prerequisites.adoc[tag=centos] +CentOS 8 * {empty} -include::partial$prerequisites.adoc[tag=debian] +Debian (Bullseye, Bookworm) * {empty} -include::partial$prerequisites.adoc[tag=red-hat] +Red Hat Enterprise Linux (9) * {empty} -include::partial$prerequisites.adoc[tag=red-hat-ibm] +Red Hat Enterprise Linux (9) on IBM Power (ppc64le) * {empty} -include::partial$prerequisites.adoc[tag=suse] +SUSE Linux Enterprise (SLES 15 SP3) * {empty} -include::partial$prerequisites.adoc[tag=suse-ibm] +SUSE Linux Enterprise (SLES 15 SP3) on IBM Power (ppc64le) * {empty} -include::partial$prerequisites.adoc[tag=ubuntu] +Ubuntu (Focal, Jammy) + +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster + +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. +[source,ssh,subs=attributes+] +---- +flexctl registration create \ +--username= \ +--password= \ +--environment= \ +--organization= \ +--output-directory=/usr/local/share/mulesoft/flex-gateway/conf.d \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-intro;sub-coll-info;user-replace-content;environment-replace-content;replace-content;reg-command-heading;reg-command-1;linux-reg-command;user-reg-command;environment-reg-command;organization-reg-command;output-reg-command-linux;reg-command-2;after-reg;linux-after-reg;create-config-folder-file;config-content;linux-start-commands] +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + + + +=== Start Commands + +Start Flex Gateway with the following command: + +[source,ssh] +---- +sudo systemctl start flex-gateway +---- + +Verify that the Flex Gateway service is running successfully: + +[source,ssh] +---- +systemctl list-units flex-gateway* +---- + +If `flex-gateway.service` has a status of `active`, Flex Gateway is successfully running. + +[source,text] +---- + UNIT LOAD ACTIVE SUB DESCRIPTION + flex-gateway.service loaded active running Application +---- [[container]] -include::partial$task-reg-run-flex-gateway.adoc[tags=user-container-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=table-containers-logos-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=table-containers-logos-links] +== Register and Run with a Username and Password in a Container +You can register and run Flex Gateway for use in one of the following containers: +[cols="1a,1a"] +|=== +|image:install-docker-logo.png[15%,15%,xref="#docker"] +|image:install-podman-logo.png[12%,12%,xref="#podman"] + +|<> +|<> +|=== [[docker]] // Register and run with a username and password in a Docker container -include::partial$task-reg-run-flex-gateway.adoc[tags=user-docker-heading;reg-command-intro;sub-coll-info-container;user-replace-content;environment-replace-content;replace-content;reg-command-heading-container;docker-create-directory-note;reg-command-1;docker-reg-command;user-reg-command;environment-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;after-reg-2;start-command-local-intro;start-command-local;start-command-local-valid] +=== Register and Run with a Username and Password in a Docker Container +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +==== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster + +==== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +IMPORTANT: Create a new directory called `flex-registration` (or similar) and then run the registration command in this new directory. The command creates registration files in this location. +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--username= \ +--password= \ +--environment= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +==== Start Command + +Run the following start command in the same directory where you ran the registration command: +[source,ssh,subs=attributes+] +---- +docker run --rm \ +-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \ +-p 8080:8080 \ +mulesoft/flex-gateway +---- +NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. + +The output logs should include this line: + +[source,ssh] +---- +[flex-gateway-envoy][info] all dependencies initialized. starting workers +---- // PODMAN [[podman]] // Register and run with a username and password in a Podmsn container -include::partial$task-reg-run-flex-gateway.adoc[tags=user-podman-heading;reg-command-intro;sub-coll-info-container;user-replace-content;environment-replace-content;replace-content;reg-command-heading-container;docker-create-directory-note;reg-command-1;podman-reg-command;user-reg-command;environment-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;after-reg-2;start-command-local-intro;podman-start-command-local;start-command-local-valid] +=== Register and Run with a Username and Password in a Podman Container +To register a Flex Gateway with Anypoint Platform, you must enter the registration command and then the start command. Each command includes information specific to your Anypoint Platform instance and *must be updated before* executing. See <> for more information on how to find the information you will need. + +==== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster + +==== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +IMPORTANT: Create a new directory called `flex-registration` (or similar) and then run the registration command in this new directory. The command creates registration files in this location. +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--username= \ +--password= \ +--environment= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + +==== Start Command + +Run the following start command in the same directory where you ran the registration command: +[source,ssh,subs=attributes+] +---- +podman run --rm \ +-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \ +-p 8080:8080 \ +docker.io/mulesoft/flex-gateway +---- +NOTE: Specify an optional name you want to assign to your Flex Replica by including the following: `-e FLEX_NAME= \`. + +The output logs should include this line: + +[source,ssh] +---- +[flex-gateway-envoy][info] all dependencies initialized. starting workers +---- // KUBERNETES [[kubernetes]] // Register and run with a username and password in a kubernetes cluster //heading -include::partial$task-reg-run-flex-gateway.adoc[tags=user-k8s-heading] +== Register and Run with a Username and Password in a Kubernetes Cluster // - task overview -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-intro-local] +Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster. + //- cluster-level access when rbac enabled, as for OpenShift -include::partial$prerequisites.adoc[tags=rbac-permission-k8] +When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC), you must have cluster-level permissions to permit installation of custom resource definitions (CRDs) used by Flex Gateway. + //- links to steps -include::partial$task-reg-run-flex-gateway.adoc[tags=links-to-k8s-reg-steps] +Complete the following steps: + +. <> +. <> +. <> + //- local mode supplemental info for k8 and openshift -include::partial$task-reg-run-flex-gateway.adoc[tag=k8s-local-intro] +In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic. + +When using this mode, you must know what resources to create and apply, and use `kubectl apply` to deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to your gateway. + +Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway routing rules. You provide this configuration through a YAML file. The file supports other properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex Gateway manages `Ingress` resources, see xref:flex-gateway-k8-ingress-class.adoc[]. [[options-k8s]] //sub collected info -include::partial$task-reg-run-flex-gateway.adoc[tags=sub-coll-info;user-replace-content;environment-replace-content;replace-content] +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster [[reg-k8s]] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading-intro] +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +You can register using one of the following container runtimes: + +// * <> +// * <> [[docker-container-reg]] .*Docker* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=docker-reg-command-heading-intro] +// ==== Docker +Run the following command to register using Docker: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;docker-reg-command;user-reg-command;environment-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg] +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--username= \ +--password= \ +--environment= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + ==== [[podman-container-reg]] .*Podman* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=podman-reg-command-heading-intro] +// ==== Podman +Run the following command to register using Podman: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;podman-reg-command;user-reg-command;environment-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg] +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--username= \ +--password= \ +--environment= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + ==== [[deploy-k8s]] //install helm chart //- title -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-title] +=== Install Helm Chart into the Namespace + //- helm chart info -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart] -include::partial$prerequisites.adoc[tags=helm] +A Helm chart installs Flex Gateway, monitoring tools, and applications. +A minimum Helm version of 3.0.0 is required. Refer to <> for configuration options. + //- add chart repo and deploy flex via chart -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart-add;k8s-flex-helm-chart-deploy-local] +. Add a Helm repository named `flex-gateway` for your chart: ++ +[source,helm] +---- +helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm +---- ++ +The command either adds the repository or skips this process if a Helm repository with that name already exists on your machine: ++ +* If the repository is new, the command returns the following message: ++ +---- +"flex-gateway" has been added to your repositories +---- ++ +* If the repository already exists, the command returns the following message: ++ +---- +"flex-gateway" already exists with the same configuration, skipping +---- + +. Run `helm repo up`. ++ +The command returns the following message: ++ +---- +Hang tight while we grab the latest from your chart repositories... +...Successfully got an update from the "flex-gateway" chart repository +Update Complete. ⎈Happy Helming!⎈ +---- ++ +If you have more than one Helm repository on your machine, the message in your terminal window lists all of the repositories. +// PLEASE retain blank line before first step below + +. Run the Helm command for deploying your gateway in Local Mode: ++ +[source,helm] +---- +helm -n gateway upgrade -i --create-namespace \ +ingress flex-gateway/flex-gateway \ +--set-file registration.content=registration.yaml +---- ++ +This command creates the `gateway` namespace and a release named `ingress` if they do not exist. You can use names of your choice for your namespace and release. The command syntax for the Helm repository and chart names is `/`. ++ +When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must have the appropriate permissions to create a load balancer in your cloud. If the load balancer is not provisioned or has issues with the provisioning process, you must choose another type by changing the `service.type` property during the installation. ++ +NOTE: By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If there's no API deployed to your Flex Gateway instance, the readiness state is `false`. This isn’t an issue with custom readiness probe configurations. ++ +When successful, the command prints a message indicating an upgrade to your `ingress` release: ++ +---- +Release "ingress" does not exist. Installing it now. +NAME: ingress +LAST DEPLOYED: Mon Mar 20 21:36:19 2023 +NAMESPACE: gateway +STATUS: deployed +REVISION: 1 +TEST SUITE: None +---- ++ +The `REVISION` value increments the `ingress` release by `1` each time you run this command with the same namespace, repository, and chart names. For example, if you run the command a second time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date of that revision. +// do not add an empty new line here at end, please [[helm-options-k8s]] //helm config options -include::partial$task-reg-run-flex-gateway.adoc[tags=helm-chart-options] +=== Helm Chart Settings + +To modify the default Helm settings with new values, such as `resource` values for CPU and memory settings, see xref:flex-gateway-k8-change-helm-settings.adoc[]. For additional Helm chart configurations, see xref:flex-gateway-k8-management.adoc[]. + +Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings: + +* Open the *flex-gateway* page in https://artifacthub.io/packages/helm/flex-gateway/flex-gateway[ArtifactHUB^] +* Run `helm show values /` from a terminal window. ++ +.Example: +[source,kubernetes] +---- +helm show values flex-gateway/flex-gateway +---- ++ +The example returns _default_ values of a repository and chart with the same name. + +To view the Helm chart `README`, run `helm show readme /` from a terminal window. + +.Example: +[source,kubernetes] +---- +helm show readme flex-gateway/flex-gateway +---- // OPENSHIFT [[openshift]] // Register and run with a username and password in a openshift cluster //heading -include::partial$task-reg-run-flex-gateway.adoc[tags=user-openshift-heading] +== Register and Run with a Username and Password in an OpenShift Cluster // - task overview -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-intro-local] +Register Flex Gateway, and then use Helm to deploy Flex Gateway to a node in your cluster. + //- cluster-level access when rbac enabled, as for OpenShift -include::partial$prerequisites.adoc[tags=rbac-permission-k8;rbac-role-openshift] +When deploying Flex Gateway to a Kubernetes cluster that enables role-based access control (RBAC), you must have cluster-level permissions to permit installation of custom resource definitions (CRDs) used by Flex Gateway. +In OpenShift, the `cluster-admin` role provides this level of access. + //- note (openshift command line procedures same as k8) -include::partial$task-reg-run-flex-gateway.adoc[tags=note-openshift-k8] +From the command line, OpenShift procedures match Kubernetes procedures. //- links to steps -include::partial$task-reg-run-flex-gateway.adoc[tags=links-to-openshift-reg-steps] +Complete the following steps: + +. <> +. <> +. <> + //- local mode supplemental info for k8 and openshift -include::partial$task-reg-run-flex-gateway.adoc[tag=k8s-local-intro] +In Local Mode, Flex Gateway typically acts as an ingress controller that manages external access to your cluster. Flex Gateway can also act as a standalone gateway for internal (east-west) traffic. + +When using this mode, you must know what resources to create and apply, and use `kubectl apply` to deploy Kubernetes targets and resources such as APIs, policies, or Flex Gateway-related resources to your gateway. + +Flex Gateway acts as an ingress controller when you apply an `Ingress` resource to configure gateway routing rules. You provide this configuration through a YAML file. The file supports other properties, such as `apiVersion`, `kind`, `metadata`, `spec` to configure a load balancer or proxy server, and `rules` for directing HTTP and HTTPS traffic. For more information about how Flex Gateway manages `Ingress` resources, see xref:flex-gateway-k8-ingress-class.adoc[]. [[options-openshift]] //sub collected info -include::partial$task-reg-run-flex-gateway.adoc[tags=sub-coll-info;user-replace-content;environment-replace-content;replace-content] +=== Collect Your Registration Data + +Before registering your Flex Gateway instance, collect information for the following registration command options: + +* `--username` = the username for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--password` = the password for an Anypoint Platform user with _Read Servers_ and _Manage Servers_ permissions for Runtime Manager +* `--environment` = the Environment Id for the environment in Anypoint Platform where you want the Flex Gateway to run +* `--organization` = your Organization ID in Anypoint Platform + +* `--split` (optional) = the flag that determines whether registration information should split into multiple files. The default value is `false`. ++ +If `split` is set to `true`, registration information is split into two files: `registration.yaml` and `certificate.yaml`. If `false`, all registration information is contained in one file: `registration.yaml`. +* `--output-directory` (optional) = the directory in which registration information is output + +* `my-gateway` = the name you want to assign the gateway cluster [[reg-openshift]] -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-heading] +=== Register Flex Gateway + +Register your Flex Gateway instance using the data that you gathered for the command options. + +You can register using one of the following container runtimes: -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-openshift-heading-intro] +// * <> +// * <> [[docker-openshift-container-reg]] .*Docker* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=docker-reg-command-heading-intro] +// ==== Docker +Run the following command to register using Docker: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;docker-reg-command;user-reg-command;environment-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg] +[source,ssh,subs=attributes+] +---- +docker run --entrypoint flexctl \ +-v "$(pwd)":/registration -u $UID mulesoft/flex-gateway \ +registration create \ +--username= \ +--password= \ +--environment= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + ==== [[podman-openshift-container-reg]] .*Podman* [%collapsible] ==== -include::partial$task-reg-run-flex-gateway.adoc[tags=podman-reg-command-heading-intro] +// ==== Podman +Run the following command to register using Podman: //reg command -include::partial$task-reg-run-flex-gateway.adoc[tags=reg-command-1;podman-reg-command;user-reg-command;environment-reg-command;organization-reg-command;output-reg-command-docker;reg-command-2;after-reg;k8s-after-reg] +[source,ssh,subs=attributes+] +---- +podman run --entrypoint flexctl --userns=keep-id \ +-v "$(pwd)":/registration:Z -u $UID docker.io/mulesoft/flex-gateway \ +registration create \ +--username= \ +--password= \ +--environment= \ +--organization= \ +--output-directory=/registration \ +my-gateway +---- + +Use `sudo` if you encounter file permission issues when running this command. + +NOTE: If you are in Europe you will need to add the `--anypoint-url=https://eu1.anypoint.mulesoft.com` flag +to your command. + +In the output directory, you should see the following new registration file(s): + +* `registration.yaml` +* `certificate.yaml` (generated only if the `split` registration parameter is set to `true`, otherwise certificate information will be contained in `registration.yaml`) + +IMPORTANT: These generated files are credentials for you to connect your Flex Gateway. If you lose them you +can no longer connect your Flex Gateway. + ==== [[deploy-openshift]] //install helm chart //- title -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-install-flex-helm-chart-title] +=== Install Helm Chart into the Namespace + //- helm chart info -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart] -include::partial$prerequisites.adoc[tags=helm] +A Helm chart installs Flex Gateway, monitoring tools, and applications. +A minimum Helm version of 3.0.0 is required. Refer to <> for configuration options. + //- add chart repo and deploy flex via chart -include::partial$task-reg-run-flex-gateway.adoc[tags=k8s-flex-helm-chart-add;k8s-flex-helm-chart-deploy-local] +. Add a Helm repository named `flex-gateway` for your chart: ++ +[source,helm] +---- +helm repo add flex-gateway https://flex-packages.anypoint.mulesoft.com/helm +---- ++ +The command either adds the repository or skips this process if a Helm repository with that name already exists on your machine: ++ +* If the repository is new, the command returns the following message: ++ +---- +"flex-gateway" has been added to your repositories +---- ++ +* If the repository already exists, the command returns the following message: ++ +---- +"flex-gateway" already exists with the same configuration, skipping +---- + +. Run `helm repo up`. ++ +The command returns the following message: ++ +---- +Hang tight while we grab the latest from your chart repositories... +...Successfully got an update from the "flex-gateway" chart repository +Update Complete. ⎈Happy Helming!⎈ +---- ++ +If you have more than one Helm repository on your machine, the message in your terminal window lists all of the repositories. +// PLEASE retain blank line before first step below + +. Run the Helm command for deploying your gateway in Local Mode: ++ +[source,helm] +---- +helm -n gateway upgrade -i --create-namespace \ +ingress flex-gateway/flex-gateway \ +--set-file registration.content=registration.yaml +---- ++ +This command creates the `gateway` namespace and a release named `ingress` if they do not exist. You can use names of your choice for your namespace and release. The command syntax for the Helm repository and chart names is `/`. ++ +When you install Flex Gateway, a Service type `LoadBalancer` is created by default. You must have the appropriate permissions to create a load balancer in your cloud. If the load balancer is not provisioned or has issues with the provisioning process, you must choose another type by changing the `service.type` property during the installation. ++ +NOTE: By default, Flex Gateways running in Kubernetes or Openshift use a readiness probe. If there's no API deployed to your Flex Gateway instance, the readiness state is `false`. This isn’t an issue with custom readiness probe configurations. ++ +When successful, the command prints a message indicating an upgrade to your `ingress` release: ++ +---- +Release "ingress" does not exist. Installing it now. +NAME: ingress +LAST DEPLOYED: Mon Mar 20 21:36:19 2023 +NAMESPACE: gateway +STATUS: deployed +REVISION: 1 +TEST SUITE: None +---- ++ +The `REVISION` value increments the `ingress` release by `1` each time you run this command with the same namespace, repository, and chart names. For example, if you run the command a second time, you find a new revision number (`REVISION: 2`). The `LAST DEPLOYED` date reflects the date of that revision. +// do not add an empty new line here at end, please [[helm-options-openshift]] //helm config options -include::partial$task-reg-run-flex-gateway.adoc[tags=helm-chart-options] +=== Helm Chart Settings + +To modify the default Helm settings with new values, such as `resource` values for CPU and memory settings, see xref:flex-gateway-k8-change-helm-settings.adoc[]. For additional Helm chart configurations, see xref:flex-gateway-k8-management.adoc[]. + +Before modifying a Helm chart for a Flex Gateway deployment, review the default Helm chart settings: + +* Open the *flex-gateway* page in https://artifacthub.io/packages/helm/flex-gateway/flex-gateway[ArtifactHUB^] +* Run `helm show values /` from a terminal window. ++ +.Example: +[source,kubernetes] +---- +helm show values flex-gateway/flex-gateway +---- ++ +The example returns _default_ values of a repository and chart with the same name. + +To view the Helm chart `README`, run `helm show readme /` from a terminal window. + +.Example: +[source,kubernetes] +---- +helm show readme flex-gateway/flex-gateway +---- == See Also diff --git a/gateway/1.9/modules/ROOT/pages/flex-local-rep-run.adoc b/gateway/1.9/modules/ROOT/pages/flex-local-rep-run.adoc index df1d244e1..c7114f7e7 100644 --- a/gateway/1.9/modules/ROOT/pages/flex-local-rep-run.adoc +++ b/gateway/1.9/modules/ROOT/pages/flex-local-rep-run.adoc @@ -17,7 +17,9 @@ include::partial$task-rep-run-flex-gateway.adoc[tags=add-flex-intro] include::partial$task-rep-run-flex-gateway.adoc[tags=add-flex-rep-byb;add-flex-rep-byb-local;add-flex-rep1] -include::partial$task-reg-run-flex-gateway.adoc[tags=create-config-folder-file;config-content;linux-start-commands] + + +include::partial$task-reg-run-flex-gateway.adoc[tags=linux-start-commands] [[docker]] == Add a Flex Replica in a Docker Container diff --git a/gateway/1.9/modules/ROOT/pages/flex-view-logs-in-runtime-manager.adoc b/gateway/1.9/modules/ROOT/pages/flex-view-logs-in-runtime-manager.adoc index b9c247524..d24c782c8 100644 --- a/gateway/1.9/modules/ROOT/pages/flex-view-logs-in-runtime-manager.adoc +++ b/gateway/1.9/modules/ROOT/pages/flex-view-logs-in-runtime-manager.adoc @@ -19,5 +19,3 @@ To access Flex Gateway runtime logs in Runtime Manager: * xref:flex-view-logs-in-monitoring.adoc[] * xref:flex-third-party-logs-config.adoc[] - -