From 5ee9d72e7a3fe4b2044bc03e60a292cbc77e76a5 Mon Sep 17 00:00:00 2001 From: shawn Date: Mon, 11 Sep 2023 13:12:14 -0700 Subject: [PATCH] Partner Experience: update the helm horizon working example (#223) --- docs/run-platform-server/running.mdx | 62 +++++++++++++++++++++------- 1 file changed, 47 insertions(+), 15 deletions(-) diff --git a/docs/run-platform-server/running.mdx b/docs/run-platform-server/running.mdx index d798a1213..ddb273b56 100644 --- a/docs/run-platform-server/running.mdx +++ b/docs/run-platform-server/running.mdx @@ -13,36 +13,68 @@ If you chose containerized installation, you don't execute the horizon binary di - To run the image as a container on docker daemon of host, use `docker run stellar/stellar-horizon: --env-file `, and specify each horizon configuration flag identified during [Configuring](./configuring.mdx) as separate line in `` of `HORIZON_CONFIG_PARAM=value`. -- To run on Kubernetes using helm chart, ensure you have followed the [pre-requisite](./installing.mdx#helm-chart-installation) of installing the Helm cli tool and adding the Stellar chart repo to helm client, now deploy the horizon helm chart to the cluster, including `--devel` uses the latest development chart version: +- To run on Kubernetes using helm chart, ensure you have followed the [pre-requisite](./installing.mdx#helm-chart-installation) of installing the Helm cli tool and adding the Stellar chart repo to helm client: - + The horizon process [requires access to a Postgres 12 database](./configuring.mdx#preparing-the-database). First use the common kubernetes cli tool `kubectl` from your workstation to create a kubernetes secret on the intended namespace of the kubernetes cluster which will hold the horizon database url. + + ```bash - helm install myhorizon stellar/horizon \ - --namespace my-horizon-namespace-on-cluster \ - --set global.image:horizon:tag=2.26.1 \ - --set global.network=testnet \ - --devel + # copy your horizon DATABASE_URL into a secure file, no line breaks. + echo -n 'database_url_here' > my_creds.txt + + # now generate the kubernetes secret from the file + kubectl create secret generic \ + -n my-namepsace\ + my-db-secret \ + --from-file=DATABASE_URL=my_creds.txt ``` - + - This example of helm chart usage, shows using the `global.network=[testnet|pubnet]` parameter, this automates generation of all the horizon configuration parameters specific to network such as archive urls, captive core config, etc and others mentioned on [Configuring](./configuring.mdx). It will also enable all three roles on the deployment instance: ingesting, api, transaction submission. If you want to customize that default behavior, don't use `global.network` and instead make your own copy of the horizon helm chart [values.yml](https://github.com/stellar/helm-charts/blob/main/charts/horizon/values.yaml), update specific configuration parameters in that file, and then pass that file: + Now deploy horizon onto the cluster using the helm chart: - + ```bash - helm install myhorizon_role stellar/horizon \ + helm install my-horizon stellar/horizon \ --namespace my-horizon-namespace-on-cluster \ - -f values.yaml \ - --devel + --set ingest.persistence.enabled=true \ + --set web.enabled=true \ + --set web.existingSecret=my-db-secret \ + --set global.image.horizon.tag=2.26.1 \ + --set global.network=testnet \ + --set ingest.existingSecret=my-db-secret \ + --set ingest.horizonConfig.captiveCoreUseDb=true \ + --set ingest.resources.limits.cpu=1 \ + --set ingest.resources.limits.memory=6Gi ``` + + + This example of helm chart usage, highlights some key aspects: + + - uses the `global.network=[testnet|pubnet]` parameter, this automates generation of all the horizon configuration parameters specific to network such as archive urls, captive core config, etc and other parameters as mentioned on [Configuring](./configuring.mdx). + - enables all roles on the deployment instance: ingesting, api, transaction submission. + - to customize further, the best approach is to download the [horizon helm chart values.yaml](https://github.com/stellar/helm-charts/blob/main/charts/horizon/values.yaml), update the settings in your local copy of values.yaml, and pass to helm install, rather than have many individual `--set` on helm install: + + + + ```bash + helm install myhorizon stellar/horizon \ + --namespace my-horizon-namespace-on-cluster \ + --values values.yaml + ``` + + - specific to customizing network configuration parameters, if you want to connect to a network other than presets of `testnet` or `pubnet`, then you won't use `global.network`, instead, use local copy of [values.yaml](https://github.com/stellar/helm-charts/blob/main/charts/horizon/values.yaml) and set `ingest.coreConfig`, and refer to [\_core-config.tpl](https://github.com/stellar/helm-charts/blob/main/charts/horizon/templates/_core-config.tpl) for example of all the key/value pairs to include. + + - minimum resource limits, verify whether `LimitRange` defaults are defined on the target namespace in kubernetes for deployment, if so, ensure that the defaults provide at least minimum resource limits of `6Gi` of memory and `1` cpu. Otherwise, define the limits explicitly on the helm install via the `ingest.resources.limits.*` shown in example, to ensure the deployed pods have adequate resources. +
-Once horizon process starts it will emit logging to standard out. When run, you should -see output similar to: + +Once the horizon process starts it will emit logging to standard out. When run, you should see output similar to: