From e51f4a624ed3555af814a4bfa7ca1065ce07968f Mon Sep 17 00:00:00 2001 From: Ilya <138466237+ikheifets-splunk@users.noreply.github.com> Date: Mon, 3 Jun 2024 10:06:23 +0200 Subject: [PATCH] fix: prettify ep docs (#2481) --- docs/edge_processor.md | 63 ++++++++++++++++++++++---------------- mkdocs.yml | 2 ++ package/sbin/entrypoint.sh | 1 + 3 files changed, 39 insertions(+), 27 deletions(-) diff --git a/docs/edge_processor.md b/docs/edge_processor.md index 313bf2d1e6..13e8177476 100644 --- a/docs/edge_processor.md +++ b/docs/edge_processor.md @@ -37,51 +37,49 @@ stateDiagram SC4S [using same protocol](https://docs.splunk.com/Documentation/SplunkCloud/latest/EdgeProcessor/HECSource) for communication with Splunk and Edge Processor. For that reason setup process will be very similar, but it have some differences. -### Set up on Docker / Podman - +/// tab | Set up on Docker / Podman 1. On the `env_file`, configure the HEC URL as IP of *managed instance*, that you registered on Edge Processor. -2. Add your HEC token. You can find your token in the Edge Processor "global settings" page. +2. Add your HEC token. You can find your token in the Edge Processor "global settings" page. ``` SC4S_DEST_SPLUNK_HEC_DEFAULT_URL=http://x.x.x.x:8088 SC4S_DEST_SPLUNK_HEC_DEFAULT_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +SC4S_DEST_SPLUNK_HEC_DEFAULT_TLS_VERIFY=no ``` +/// -### Kubernetes - +/// tab | Set up on Kubernetes 1. Set up the Edge Processor on your `values.yaml` HEC URL using the IP of *managed instance*, that you registered on Edge Processor. - 2. Provide the hec_token. You can find this token on the Edge Processor's "global settings" page. ``` splunk: hec_url: "http://x.x.x.x:8088" hec_token: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + hec_verify_tls: "no" ``` +/// ## mTLS encryption -### Prepare your certificates - Before setup, [generate mTLS certificates](https://docs.splunk.com/Documentation/SplunkCloud/latest/EdgeProcessor/SecureForwarders). Server mTLS certificates should be uploaded to `Edge Processor` and client certifcates should be used with `SC4S`. -Rename the certificate files. SC4S requires the following names: +**Rename the certificate files. SC4S requires the following names**: * `key.pem` - client certificate key * `cert.pem` - client certificate * `ca_cert.pem` - certificate authority -### Docker / Podman +/// tab | Set up on Docker / Podman +1. Use HTTPS in HEC url: `SC4S_DEST_SPLUNK_HEC_DEFAULT_URL=https://x.x.x.x:8088`. +2. Move your clients mTLS certificates (`key.pem`, `cert.pem`, `ca_cert.pem`) to `/opt/sc4s/tls/hec`. +3. Mount `/opt/sc4s/tls/hec` to `/etc/syslog-ng/tls/hec` using docker/podman volumes. +4. Define mounting mTLS point for HEC: `SC4S_DEST_SPLUNK_HEC_DEFAULT_TLS_MOUNT=/etc/syslog-ng/tls/hec`. +5. Start or restart SC4S. +/// - 1. Use HTTPS in HEC url: `SC4S_DEST_SPLUNK_HEC_DEFAULT_URL=https://x.x.x.x:8088`. - 2. Move your clients mTLS certificates to `/opt/sc4s/tls/hec`. - 3. Mount `/opt/sc4s/tls/hec` to `/etc/syslog-ng/tls/hec` using docker/podman volumes. - 4. Define mounting mTLS point for HEC: `SC4S_DEST_SPLUNK_HEC_DEFAULT_TLS_MOUNT=/etc/syslog-ng/tls/hec`. - 5. Start or restart SC4S. - -### Kubernetes - - 1. Add the secret name of the mTLS certificates to the `values.yaml` file: +/// tab | Set up on Kubernetes +1. Add the secret name of the mTLS certificates to the `values.yaml` file: ``` splunk: @@ -90,7 +88,7 @@ splunk: hec_tls: "hec-tls-secret" ``` - 2. Add your mTLS certificates to the `charts/splunk-connect-for-syslog/secrets.yaml` file: +2. Add your mTLS certificates to the `charts/splunk-connect-for-syslog/secrets.yaml` file: ``` hec_tls: @@ -110,27 +108,38 @@ hec_tls: -----END CERTIFICATE----- ``` - 3. Encrypt your `secrets.yaml` using `ansible-vault encrypt charts/splunk-connect-for-syslog/secrets.yaml`. - 4. Add the IP address for your cluster nodes to the inventory file `ansible/inventory/inventory_microk8s_ha.yaml`. - 5. Deploy the Ansible playbook `ansible-playbook -i ansible/inventory/inventory_microk8s_ha.yaml ansible/playbooks/microk8s_ha.yml --ask-vault-pass` +3. Encrypt your `secrets.yaml`: + +``` +ansible-vault encrypt charts/splunk-connect-for-syslog/secrets.yaml +``` + +4. Add the IP address for your cluster nodes to the inventory file `ansible/inventory/inventory_microk8s_ha.yaml`. + +5. Deploy the Ansible playbook: + +``` +ansible-playbook -i ansible/inventory/inventory_microk8s_ha.yaml ansible/playbooks/microk8s_ha.yml --ask-vault-pass +``` +/// ## Scaling Edge Processor To scale you can distribute traffic between Edge Processor **managed instances**. To set this up, update the HEC URL with a comma-separated list of URLs for your managed instances. -### Docker/Podman - +/// tab | Set up on Docker/Podman Update HEC URL in `env_file`: ``` SC4S_DEST_SPLUNK_HEC_DEFAULT_URL=http://x.x.x.x:8088,http://x.x.x.x:8088,http://x.x.x.x:8088 ``` +/// -### Kubernetes - +/// tab | Set up on Kubernetes Update HEC URL in `values.yaml`: ``` splunk: hec_url: "http://x.x.x.x:8088,http://x.x.x.x:8088,http://x.x.x.x:8088" ``` +/// diff --git a/mkdocs.yml b/mkdocs.yml index 806ae86867..187e6cff8d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,6 +19,8 @@ markdown_extensions: - name: mermaid class: mermaid format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.blocks.tab: + alternate_style: true theme: diff --git a/package/sbin/entrypoint.sh b/package/sbin/entrypoint.sh index 924a1b1965..ca7ec01542 100755 --- a/package/sbin/entrypoint.sh +++ b/package/sbin/entrypoint.sh @@ -171,6 +171,7 @@ then HEC=$(echo $SC4S_DEST_SPLUNK_HEC_DEFAULT_URL | cut -d' ' -f 1) if [ "${SC4S_DEST_SPLUNK_HEC_DEFAULT_TLS_VERIFY}" == "no" ]; then export NO_VERIFY=-k ; fi + export SC4S_DEST_SPLUNK_HEC_DEFAULT_TLS_MOUNT=${SC4S_DEST_SPLUNK_HEC_DEFAULT_TLS_MOUNT:=${SC4S_DEST_TLS_MOUNT}} if [ -n "${SC4S_DEST_SPLUNK_HEC_DEFAULT_TLS_MOUNT}" ]; then export HEC_TLS_OPTS="--cert ${SC4S_DEST_SPLUNK_HEC_DEFAULT_TLS_MOUNT}/cert.pem --key ${SC4S_DEST_SPLUNK_HEC_DEFAULT_TLS_MOUNT}/key.pem --cacert ${SC4S_DEST_SPLUNK_HEC_DEFAULT_TLS_MOUNT}/ca_cert.pem"; else