diff --git a/docs/Gemfile b/docs/Gemfile index 62e497223..dca74fad3 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -13,14 +13,14 @@ source "https://rubygems.org" # uncomment the line below. To upgrade, run `bundle update github-pages`. gem "github-pages", group: :jekyll_plugins # If you have any plugins, put them here! -group :jekyll_plugins do - gem "jekyll-feed", "~> 0.12" - gem "jekyll-external-links" -end +# group :jekyll_plugins do +# gem "jekyll-feed", "~> 0.12" +# gem "jekyll-external-links" +# end # Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem # do not have a Java counterpart. -gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby] +# gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby] gem "webrick", "~> 1.8" gem "just-the-docs", "~> 0.7.0" \ No newline at end of file diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 818220f4d..ad50c4906 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -18,7 +18,7 @@ GEM coffee-script (2.4.1) coffee-script-source execjs - coffee-script-source (1.12.2) + coffee-script-source (1.11.1) colorator (1.1.0) commonmarker (0.23.10) concurrent-ruby (1.2.3) @@ -40,24 +40,24 @@ GEM net-http ffi (1.16.3) forwardable-extended (2.6.0) - gemoji (4.1.0) - github-pages (229) - github-pages-health-check (= 1.18.2) - jekyll (= 3.9.4) - jekyll-avatar (= 0.8.0) - jekyll-coffeescript (= 1.2.2) + gemoji (3.0.1) + github-pages (228) + github-pages-health-check (= 1.17.9) + jekyll (= 3.9.3) + jekyll-avatar (= 0.7.0) + jekyll-coffeescript (= 1.1.1) jekyll-commonmark-ghpages (= 0.4.0) - jekyll-default-layout (= 0.1.5) - jekyll-feed (= 0.17.0) + jekyll-default-layout (= 0.1.4) + jekyll-feed (= 0.15.1) jekyll-gist (= 1.5.0) - jekyll-github-metadata (= 2.16.1) + jekyll-github-metadata (= 2.13.0) jekyll-include-cache (= 0.2.1) jekyll-mentions (= 1.6.0) jekyll-optional-front-matter (= 0.3.2) jekyll-paginate (= 1.1.0) jekyll-readme-index (= 0.3.0) jekyll-redirect-from (= 0.16.0) - jekyll-relative-links (= 0.7.0) + jekyll-relative-links (= 0.6.1) jekyll-remote-theme (= 0.4.3) jekyll-sass-converter (= 1.5.2) jekyll-seo-tag (= 2.8.0) @@ -77,20 +77,20 @@ GEM jekyll-theme-tactile (= 0.2.0) jekyll-theme-time-machine (= 0.2.0) jekyll-titles-from-headings (= 0.5.3) - jemoji (= 0.13.0) - kramdown (= 2.4.0) + jemoji (= 0.12.0) + kramdown (= 2.3.2) kramdown-parser-gfm (= 1.1.0) liquid (= 4.0.4) mercenary (~> 0.3) minima (= 2.5.1) nokogiri (>= 1.13.6, < 2.0) - rouge (= 3.30.0) + rouge (= 3.26.0) terminal-table (~> 1.4) - github-pages-health-check (1.18.2) + github-pages-health-check (1.17.9) addressable (~> 2.3) dnsruby (~> 1.60) - octokit (>= 4, < 8) - public_suffix (>= 3.0, < 6.0) + octokit (~> 4.0) + public_suffix (>= 3.0, < 5.0) typhoeus (~> 1.3) html-pipeline (2.14.3) activesupport (>= 2) @@ -98,7 +98,7 @@ GEM http_parser.rb (0.8.0) i18n (1.14.1) concurrent-ruby (~> 1.0) - jekyll (3.9.4) + jekyll (3.9.3) addressable (~> 2.4) colorator (~> 1.0) em-websocket (~> 0.5) @@ -111,11 +111,11 @@ GEM pathutil (~> 0.9) rouge (>= 1.7, < 4) safe_yaml (~> 1.0) - jekyll-avatar (0.8.0) + jekyll-avatar (0.7.0) jekyll (>= 3.0, < 5.0) - jekyll-coffeescript (1.2.2) + jekyll-coffeescript (1.1.1) coffee-script (~> 2.2) - coffee-script-source (~> 1.12) + coffee-script-source (~> 1.11.1) jekyll-commonmark (1.4.0) commonmarker (~> 0.22) jekyll-commonmark-ghpages (0.4.0) @@ -123,18 +123,15 @@ GEM jekyll (~> 3.9.0) jekyll-commonmark (~> 1.4.0) rouge (>= 2.0, < 5.0) - jekyll-default-layout (0.1.5) - jekyll (>= 3.0, < 5.0) - jekyll-external-links (0.1.3) - jekyll (~> 3.8) - nokogiri - jekyll-feed (0.17.0) + jekyll-default-layout (0.1.4) + jekyll (~> 3.0) + jekyll-feed (0.15.1) jekyll (>= 3.7, < 5.0) jekyll-gist (1.5.0) octokit (~> 4.2) - jekyll-github-metadata (2.16.1) + jekyll-github-metadata (2.13.0) jekyll (>= 3.4, < 5.0) - octokit (>= 4, < 7, != 4.4.0) + octokit (~> 4.0, != 4.4.0) jekyll-include-cache (0.2.1) jekyll (>= 3.7, < 5.0) jekyll-mentions (1.6.0) @@ -147,7 +144,7 @@ GEM jekyll (>= 3.0, < 5.0) jekyll-redirect-from (0.16.0) jekyll (>= 3.3, < 5.0) - jekyll-relative-links (0.7.0) + jekyll-relative-links (0.6.1) jekyll (>= 3.3, < 5.0) jekyll-remote-theme (0.4.3) addressable (~> 2.0) @@ -205,8 +202,8 @@ GEM jekyll (>= 3.3, < 5.0) jekyll-watch (2.2.1) listen (~> 3.0) - jemoji (0.13.0) - gemoji (>= 3, < 5) + jemoji (0.12.0) + gemoji (~> 3.0) html-pipeline (~> 2.2) jekyll (>= 3.0, < 5.0) just-the-docs (0.7.0) @@ -214,7 +211,7 @@ GEM jekyll-include-cache jekyll-seo-tag (>= 2.0) rake (>= 12.3.1) - kramdown (2.4.0) + kramdown (2.3.2) rexml kramdown-parser-gfm (1.1.0) kramdown (~> 2.0) @@ -248,14 +245,14 @@ GEM sawyer (~> 0.9) pathutil (0.16.2) forwardable-extended (~> 2.6) - public_suffix (5.0.4) + public_suffix (4.0.7) racc (1.7.3) rake (13.1.0) rb-fsevent (0.11.2) rb-inotify (0.10.1) ffi (~> 1.0) rexml (3.2.6) - rouge (3.30.0) + rouge (3.26.0) ruby2_keywords (0.0.5) rubyzip (2.3.2) safe_yaml (1.0.5) @@ -292,9 +289,6 @@ PLATFORMS DEPENDENCIES github-pages - http_parser.rb (~> 0.6.0) - jekyll-external-links - jekyll-feed (~> 0.12) just-the-docs (~> 0.7.0) webrick (~> 1.8) diff --git a/docs/_config.yml b/docs/_config.yml index 57c91acc5..1029a5332 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,72 +1,83 @@ -defaults: - - - scope: - path: "" - type: "pages" - values: - layout: "default" - title: Splunk Operator for Kubernetes #email: your-email@example.com -description: >- # this means to ignore newlines until "baseurl:" +description: >- The Splunk Operator for Kubernetes (SOK) makes it easy for Splunk Administrators to deploy and operate Enterprise deployments in a Kubernetes infrastructure. Packaged as a container, it uses the operator pattern to manage Splunk-specific custom resources, following best practices to manage all the underlying Kubernetes objects for you. github_username: mcinnesd domain: mcinnesd.github.io -url: "https://mcinnesd.github.io" # the base hostname & protocol for your site, e.g. http://example.com - +url: "https://mcinnesd.github.io" favicon_ico: /assets/images/favicon.ico - aux_links: "Splunk Operator for Kubernetes on GitHub": - "//github.com/mcinnesd/splunk-operator" -operator_release_version: "2.5.0" - # Build settings theme: just-the-docs plugins: - jekyll-external-links + # - jekyll-feed + +krmadown: + toc_levels: [1, 2, 3] collections: helm: permalink: "/:path/" output: true + installation: + permalink: "/:collection/:path" + output: true + configuration: + permalink: "/:collection/:path" + output: true + troubleshooting: + permalink: "/:collection/:path" + output: true +just_the_docs: + collections: + installation: + name: Installation + nav_fold: true + configuration: + name: Configuration + nav_fold: true + troubleshooting: + name: Troubleshooting + nav_fold: true # The colors grey-lt, grey-dk, purple, # blue, green, yellow, and red are predefined callouts: - warning: - title: Warning - color: yellow note: title: Note color: blue highlight: color: yellow - important: - title: Important - color: red - -# Exclude from processing. -# The following items will not be processed, by default. -# Any item listed under the `exclude:` key here will be automatically added to -# the internal "default list". -# -# Excluded items can be processed by explicitly listing the directories or -# their entries' file path in the `include:` list. -# -# exclude: -# - .sass-cache/ -# - .jekyll-cache/ -# - gemfiles/ -# - Gemfile -# - Gemfile.lock -# - node_modules/ -# - vendor/bundle/ -# - vendor/cache/ -# - vendor/gems/ -# - vendor/ruby/ +defaults: + - + scope: + path: "" + type: "pages" + values: + nav_after_collections: false + - + scope: + path: "" + type: "installation" + values: + layout: "default" + - + scope: + path: "" + type: "configuration" + values: + layout: "default" + - + scope: + path: "" + type: "troubleshooting" + values: + layout: "default" \ No newline at end of file diff --git a/docs/configuration/AppFramework.md b/docs/_configuration/AppFramework.md similarity index 99% rename from docs/configuration/AppFramework.md rename to docs/_configuration/AppFramework.md index 55a2e3c63..1a9ad20c2 100644 --- a/docs/configuration/AppFramework.md +++ b/docs/_configuration/AppFramework.md @@ -1,7 +1,7 @@ --- title: App Framework nav_order: 21 -#nav_exclude: true +layout: "default" --- # App Framework Resource Guide diff --git a/docs/configuration/CustomResources.md b/docs/_configuration/CustomResources.md similarity index 80% rename from docs/configuration/CustomResources.md rename to docs/_configuration/CustomResources.md index e69088bca..778991041 100644 --- a/docs/configuration/CustomResources.md +++ b/docs/_configuration/CustomResources.md @@ -5,29 +5,19 @@ nav_order: 31 --- # Custom Resource Guide - +{: .no_toc } The Splunk Operator provides a collection of [custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) you can use to manage Splunk Enterprise deployments in your Kubernetes cluster. -- [Custom Resource Guide](#custom-resource-guide) - - [Metadata Parameters](#metadata-parameters) - - [Common Spec Parameters for All Resources](#common-spec-parameters-for-all-resources) - - [Common Spec Parameters for Splunk Enterprise Resources](#common-spec-parameters-for-splunk-enterprise-resources) - - [LicenseManager Resource Spec Parameters](#licensemanager-resource-spec-parameters) - - [Standalone Resource Spec Parameters](#standalone-resource-spec-parameters) - - [SearchHeadCluster Resource Spec Parameters](#searchheadcluster-resource-spec-parameters) - - [ClusterManager Resource Spec Parameters](#clustermanager-resource-spec-parameters) - - [IndexerCluster Resource Spec Parameters](#indexercluster-resource-spec-parameters) - - [MonitoringConsole Resource Spec Parameters](#monitoringconsole-resource-spec-parameters) - - [Examples of Guaranteed and Burstable QoS](#examples-of-guaranteed-and-burstable-qos) - - [A Guaranteed QoS Class example:](#a-guaranteed-qos-class-example) - - [A Burstable QoS Class example:](#a-burstable-qos-class-example) - - [A BestEffort QoS Class example:](#a-besteffort-qos-class-example) - - [Pod Resources Management](#pod-resources-management) - For examples on how to use these custom resources, please see -[Configuring Splunk Enterprise Deployments](Examples.md). +[Configuring Splunk Enterprise Deployments](/configuration/Examples). + + +#### Table of contents +{: .no_toc } +- TOC +{:toc} ## Metadata Parameters @@ -295,64 +285,3 @@ The Splunk Operator now includes a CRD for the Monitoring Console (MC). This off The MC pod is referenced by using the `monitoringConsoleRef` parameter. There is no preferred order when running an MC pod; you can start the pod before or after the other CR's in the namespace. When a pod that references the `monitoringConsoleRef` parameter is created or deleted, the MC pod will automatically update itself and create or remove connections to those pods. - -## Examples of Guaranteed and Burstable QoS - -You can change the CPU and memory resources, and assign different Quality of Services (QoS) classes to your pods using the [Kubernetes Quality of Service section](README.md#using-kubernetes-quality-of-service-classes). Here are some examples: - -### A Guaranteed QoS Class example: -Set equal ```requests``` and ```limits``` values for CPU and memory to establish a QoS class of Guaranteed. - -*Note: A pod will not start on a node that cannot meet the CPU and memory ```requests``` values.* - -Example: The minimum resource requirements for a Standalone Splunk Enterprise instance in production are 24 vCPU and 12GB RAM. - -```yaml -apiVersion: enterprise.splunk.com/v4 -kind: Standalone -metadata: - name: example -spec: - imagePullPolicy: Always - resources: - requests: - memory: "12Gi" - cpu: "24" - limits: - memory: "12Gi" - cpu: "24" -``` - -### A Burstable QoS Class example: -Set the ```requests``` value for CPU and memory lower than the ```limits``` value to establish a QoS class of Burstable. - -Example: This Standalone Splunk Enterprise instance should start with minimal indexing and search capacity, but will be allowed to scale up if Kubernetes is able to allocate additional CPU and Memory up to the ```limits``` values. - -```yaml -apiVersion: enterprise.splunk.com/v4 -kind: Standalone -metadata: - name: example -spec: - imagePullPolicy: Always - resources: - requests: - memory: "2Gi" - cpu: "4" - limits: - memory: "12Gi" - cpu: "24" -``` - -### A BestEffort QoS Class example: -With no requests or limits values set for CPU and memory, the QoS class is set to BestEffort. The BestEffort QoS is not recommended for use with Splunk Operator. - -### Pod Resources Management - -__CPU Throttling__ - -Kubernetes starts throttling CPUs if a pod's demand for CPU exceeds the value set in the ```limits``` parameter. If your nodes have extra CPU resources available, leaving the ```limits``` value unset will allow the pods to utilize more CPUs. - -__POD Eviction - OOM__ - -As oppose to throttling in case of CPU cycles starvation, Kubernetes will evict a pod from the node if the pod's memory demands exceeds the value set in the ```limits``` parameter. diff --git a/docs/configuration/Examples.md b/docs/_configuration/Examples.md similarity index 83% rename from docs/configuration/Examples.md rename to docs/_configuration/Examples.md index 58e2493ff..12efc015e 100644 --- a/docs/configuration/Examples.md +++ b/docs/_configuration/Examples.md @@ -5,46 +5,14 @@ nav_order: 28 --- # Configuring Splunk Enterprise Deployments - +{: .no_toc } This document includes various examples for configuring Splunk Enterprise deployments with the Splunk Operator. +For more information about the custom resources that you can use with the Splunk Operator, refer to the [Custom Resource Guide](/configuration/CustomResources). - -- [Configuring Splunk Enterprise Deployments](#configuring-splunk-enterprise-deployments) - - [Creating a Clustered Deployment](#creating-a-clustered-deployment) - - [Indexer Clusters](#indexer-clusters) - - [Cluster Manager](#cluster-manager) - - [Indexer cluster peers](#indexer-cluster-peers) - - [Scaling cluster peers using replicas](#scaling-cluster-peers-using-replicas) - - [Scaling cluster peers using pod autoscaling](#scaling-cluster-peers-using-pod-autoscaling) - - [Create a search head for your index cluster](#create-a-search-head-for-your-index-cluster) - - [Another Cluster Manager example](#another-cluster-manager-example) - - [Monitoring Console](#monitoring-console) - - [Search Head Clusters](#search-head-clusters) - - [Cluster Services](#cluster-services) - - [Cleaning Up](#cleaning-up) - - [SmartStore Index Management](#smartstore-index-management) - - [Using Default Settings](#using-default-settings) - - [Installing Splunk Apps](#installing-splunk-apps) - - [Creating a LicenseManager Using a ConfigMap](#creating-a-licensemanager-using-a-configmap) - - [Configuring Standalone to use License Manager](#configuring-standalone-to-use-license-manager) - - [Configuring Indexer Clusters to use License Manager](#configuring-indexer-clusters-to-use-license-manager) - - [Using an External License Manager](#using-an-external-license-manager) - - [Configuring pass4Symmkey:](#configuring-pass4symmkey) - - [Approach 1](#approach-1) - - [Approach 2](#approach-2) - - [Configuring license\_master\_url:](#configuring-license_master_url) - - [Using an External Indexer Cluster](#using-an-external-indexer-cluster) - - [Configuring IDXC pass4Symmkey:](#configuring-idxc-pass4symmkey) - - [Approach 1](#approach-1-1) - - [Approach 2](#approach-2-1) - - [Configuring cluster\_master\_url:](#configuring-cluster_master_url) - - [Managing global kubernetes secret object](#managing-global-kubernetes-secret-object) - - [Creating global kubernetes secret object](#creating-global-kubernetes-secret-object) - - [Reading global kubernetes secret object](#reading-global-kubernetes-secret-object) - - [Updating global kubernetes secret object](#updating-global-kubernetes-secret-object) - - [Deleting global kubernetes secret object](#deleting-global-kubernetes-secret-object) - -For more information about the custom resources that you can use with the Splunk Operator, refer to the [Custom Resource Guide](CustomResources.md). +#### Table of contents +{: .no_toc } +- TOC +{:toc} ## Creating a Clustered Deployment @@ -68,6 +36,7 @@ When customers outgrow the capabilites of single instance for indexing and searc The Splunk Operator makes creation of a cluster easy by utilizing a `ClusterManager` resource for Cluster Manager, and using the `IndexerCluster` resource for the cluster peers: #### Cluster Manager +{: .no_toc } ```yaml cat <-secret -o jsonpath='{.data.password}' | base64 --decode ``` -See [Configuring Ingress](Ingress.md) for guidance on making your Splunk Enterprise clusters accessible from outside of Kubernetes. +See [Configuring Ingress](/configuration/Ingress) for guidance on making your Splunk Enterprise clusters accessible from outside of Kubernetes. ### Cleaning Up @@ -417,7 +394,7 @@ kubectl delete -n splunk-opertaor clustermanager cm ## SmartStore Index Management -Indexes can be managed through the Splunk Operator. Every index configured through the Splunk Operator must be SmartStore enabled. See [SmartStore Resource Guide](SmartStore.md). +Indexes can be managed through the Splunk Operator. Every index configured through the Splunk Operator must be SmartStore enabled. See [SmartStore Resource Guide](/configuration/SmartStore). ## Using Default Settings @@ -468,15 +445,16 @@ app installation. Inline `defaults` are always processed last, after any `defaultsUrl` files. Any password management related configuration via `defaults` and `defaultsUrl` -has been disabled. Please review [`PasswordManagement.md`](PasswordManagement.md) +has been disabled. Please review [`PasswordManagement.md`](/configuration/PasswordManagement) and [`Managing global kubernetes secret object`](#managing-global-kubernetes-secret-object) for more details. ## Installing Splunk Apps -*Note that this requires using the Splunk Enterprise container version 9.0.0 or later* +{: .note } +This requires using the Splunk Enterprise container version 9.0.0 or later* -With the Splunk Operator 2.0 release, new App Framework is available to centrally store and deploy apps. See [AppFramework](AppFramework.md) for information and examples. +With the Splunk Operator 2.0 release, new App Framework is available to centrally store and deploy apps. See [AppFramework](/configuration/AppFramework) for information and examples. ## Creating a LicenseManager Using a ConfigMap @@ -519,9 +497,8 @@ the `enterprise.lic` file within it. licenseUrl: "/mnt/licenses/enterprise1.lic,/mnt/licenses/enterprise2.lic" ``` -Note that `licenseUrl` may specify a local path or URL such as -"https://myco.com/enterprise.lic", and the `volumes` parameter can -be used to mount any type of [Kubernetes Volumes](https://kubernetes.io/docs/concepts/storage/volumes/). +{: .note } +`licenseUrl` may specify a local path or URL such as "https://myco.com/enterprise.lic", and the `volumes` parameter can be used to mount any type of [Kubernetes Volumes](https://kubernetes.io/docs/concepts/storage/volumes/). ## Configuring Standalone to use License Manager @@ -543,7 +520,7 @@ spec: ## Configuring Indexer Clusters to use License Manager -While configuring [`Indexer Clusters`](Examples.md#indexer-clusters) to use the `LicenseManager`, you need to add `licenseManagerRef` only to the `ClusterManager` spec as follows: +While configuring [`Indexer Clusters`](#indexer-clusters) to use the `LicenseManager`, you need to add `licenseManagerRef` only to the `ClusterManager` spec as follows: ```yaml cat <` +1. Verify the namespace. You can retrieve the namespace in the current context using `kubectl config view --minify --output 'jsonpath={..namespace}'`. Make a note of the output. If the command doesn't display an output it indicates that we are in the `default` namespace. +{: .note } +If you already have a desired namespace, you can set current context to the same using the following command: `kubectl config set-context --current --namespace=` -2. Gather the password values for the secret tokens you want to configure. To see all available secret tokens defined for the global kubernetes secret object, review [password management](PasswordManagement.md#splunk-secret-tokens-in-the-global-secret-object) +2. Gather the password values for the secret tokens you want to configure. To see all available secret tokens defined for the global kubernetes secret object, review [password management](/configuration/PasswordManagement#splunk-secret-tokens-in-the-global-secret-object) 3. Create a kubernetes secret object referencing the namespace. Example: splunk-`-secret. In the example below, we are creating the global kubernetes secret object, defining the default administrator and pass4Symmkey tokens, and passing in the values. @@ -799,7 +784,7 @@ shc_secret: dGGXnNogsL8V4yhp1bajbrZ5 Use the kubectl command to update the global kubernetes secret object: 1. Base64 encode the plain-text value of the secret token using the following command: `echo -n | base64` -2. Obtain the key name for the secret token you are populating. The list of tokens is available in [password management](PasswordManagement.md#splunk-secret-tokens-in-the-global-secret-object). +2. Obtain the key name for the secret token you are populating. The list of tokens is available in [password management](/configuration/PasswordManagement#splunk-secret-tokens-in-the-global-secret-object). 3. Update the global kubernetes secret object using the key and the encoded value: `kubectl patch secret splunk--secret -p='{"data":{"": ""}}' -v=1` ### Deleting global kubernetes secret object diff --git a/docs/configuration/Ingress.md b/docs/_configuration/Ingress.md similarity index 97% rename from docs/configuration/Ingress.md rename to docs/_configuration/Ingress.md index 1cb72b9be..93fcc5c18 100644 --- a/docs/configuration/Ingress.md +++ b/docs/_configuration/Ingress.md @@ -35,19 +35,19 @@ We provide some examples below for configuring a few of the most popular Ingress Before deploying an example, you will need to review the yaml and replace “example.com” with the domain name you would like to use and replace “example” in the service names with the name of your custom resource object. You will also need to point your DNS for all the desired hostnames to the IP addresses of your ingress load balancer. -#### Important Notes on using Splunk on Kubernetes +### Important Notes on using Splunk on Kubernetes -#### Load Balancer Requirements +##### Load Balancer Requirements When configuring ingress for use with Splunk Forwarders, the configured ingress load balancer must resolve to two or more IPs. This is required so the auto load balancing capability of the forwarders is preserved. -#### Splunk default network ports +##### Splunk default network ports When creating a new Splunk instance on Kubernetes, the default network ports will be used for internal communication such as internal logs, replication, and others. Any change in how these ports are configured needs to be consistent across the cluster. For Ingress we recommend using separate ports for encrypted and non-encrypted traffic. In this documentation we will use port 9998 for encrypted data coming from outside the cluster, while keeping the default 9997 for non-encrypted intra-cluster communication. For example, this [ServiceTemplate configuration](#serviceTemplate) creates a standalone instance with port 9998 exposed. -#### Indexer Discovery is not supported +##### Indexer Discovery is not supported Indexer Discovery is not supported on a Kubernetes cluster. Instead, the Ingress controllers will be responsible to connect forwarders to peer nodes in Indexer clusters. @@ -63,7 +63,7 @@ Most scenarios for Istio will require the configuration of a Gateway and a Virtu You can configure Istio to provide direct access to Splunk Web. -#### Standalone Configuration +##### Standalone Configuration 1. Create a Gateway to receive traffic on port 80 @@ -118,7 +118,7 @@ kubectl get svc -n istio-system http:// ``` -#### Multiple Hosts and HEC Configuration +##### Multiple Hosts and HEC Configuration If your deployment has multiple hosts such as Search Heads and Cluster Manager, use this example to configure Splunk Web access, and HTTP Event Collector port. Follow the steps here [HEC Documentation](https://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector) to learn how to create a HEC token and how to send data using HTTP. @@ -303,7 +303,7 @@ kubectl get svc -n istio-system ### Configuring Ingress for Splunk Forwarder data with TLS It is highly recommended that you always use TLS encryption for your Splunk Enterprise endpoints. The following sections will cover the two main configurations supported by Istio. -#### Splunk Forwarder data with end-to-end TLS +##### Splunk Forwarder data with end-to-end TLS In this configuration Istio passes the encrypted traffic to Splunk Enterprise without any termination. Note that you need to configure the TLS certificates on the Forwarder as well as any Splunk Enterprise indexers, cluster peers, or standalone instances. @@ -393,7 +393,7 @@ If you only have one indexer cluster that you would like to use as the destinati Configure the Forwarder's outputs.conf and the Indexer's inputs.conf using the documentation [Configure Secure Forwarding](https://docs.splunk.com/Documentation/Splunk/latest/Security/Aboutsecuringdatafromforwarders) -#### Splunk Forwarder data with TLS Gateway Termination +##### Splunk Forwarder data with TLS Gateway Termination In this configuration, Istio is terminating the encryption at the Gateway and forwarding the decrypted traffic to Splunk Enterprise. Note that in this case the Forwarder's outputs.conf should be configured for TLS, while the Indexer's input.conf should be configured to accept non-encrypted traffic. @@ -688,7 +688,7 @@ The Nginx Ingress Controller is an open source version of the F5 product. Please We followed the product's Helm Chart installation guide. It requires a cluster with internet access. [NGINX Ingress Controller Helm Installation]( https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/) -#### Setup Helm +##### Setup Helm ```shell # clone the repo and check out the current production branch @@ -704,7 +704,7 @@ $ helm repo update $ kubectl create -f crds/ ``` -#### Install Ingress +##### Install Ingress ```shell cd deployments/helm-chart @@ -721,7 +721,7 @@ splunk-nginx default 5 2020-10-29 15:03:47.6 EDT deployed nginx-ingr helm upgrade splunk-nginx nginx-stable/nginx-ingress ``` -#### Configure Ingress services +##### Configure Ingress services ##### Configure Ingress for Splunk Web and HEC @@ -777,7 +777,6 @@ status: Enable the global configuration to setup a listener and transport server 1. Create the GlobalConfiguration: - ```yaml apiVersion: k8s.nginx.org/v1alpha1 kind: GlobalConfiguration @@ -806,19 +805,17 @@ spec: ``` 2. Edit the service to establish a node-port for the port being setup as the listener: - 1. List the service: - -```yaml -kubectl get svc -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -splunk-nginx-nginx-ingress LoadBalancer 172.20.195.54 aa725344587a4443b97c614c6c78419c-1675645062.us-east-2.elb.amazonaws.com 80:31452/TCP,443:30402/TCP,30403:30403/TCP 7d1h -``` - -​ 2. Edit the service and add the Splunk Forwarder ingress port: - -``` -kubectl edit service splunk-nginx-nginx-ingress -``` + 1. List the service: + ```yaml + kubectl get svc + NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + splunk-nginx-nginx-ingress LoadBalancer 172.20.195.54 aa725344587a4443b97c614c6c78419c-1675645062.us-east-2.elb.amazonaws.com 80:31452/TCP,443:30402/TCP,30403:30403/TCP 7d1h + ``` + + 2. Edit the service and add the Splunk Forwarder ingress port: + ``` + kubectl edit service splunk-nginx-nginx-ingress + ``` Example Service: ```yaml diff --git a/docs/configuration/KubernetesQOS.md b/docs/_configuration/KubernetesQOS.md similarity index 100% rename from docs/configuration/KubernetesQOS.md rename to docs/_configuration/KubernetesQOS.md diff --git a/docs/configuration/MultisiteExamples.md b/docs/_configuration/MultisiteExamples.md similarity index 100% rename from docs/configuration/MultisiteExamples.md rename to docs/_configuration/MultisiteExamples.md diff --git a/docs/configuration/PasswordManagement.md b/docs/_configuration/PasswordManagement.md similarity index 100% rename from docs/configuration/PasswordManagement.md rename to docs/_configuration/PasswordManagement.md diff --git a/docs/configuration/PremiumApps.md b/docs/_configuration/PremiumApps.md similarity index 100% rename from docs/configuration/PremiumApps.md rename to docs/_configuration/PremiumApps.md diff --git a/docs/configuration/Security.md b/docs/_configuration/Security.md similarity index 100% rename from docs/configuration/Security.md rename to docs/_configuration/Security.md diff --git a/docs/configuration/SmartStore.md b/docs/_configuration/SmartStore.md similarity index 100% rename from docs/configuration/SmartStore.md rename to docs/_configuration/SmartStore.md diff --git a/docs/configuration/StorageClass.md b/docs/_configuration/StorageClass.md similarity index 100% rename from docs/configuration/StorageClass.md rename to docs/_configuration/StorageClass.md diff --git a/docs/configuration/Telemetry.md b/docs/_configuration/Telemetry.md similarity index 100% rename from docs/configuration/Telemetry.md rename to docs/_configuration/Telemetry.md diff --git a/docs/_includes/components/site_nav.html b/docs/_includes/components/site_nav.html new file mode 100644 index 000000000..c794d39a5 --- /dev/null +++ b/docs/_includes/components/site_nav.html @@ -0,0 +1,76 @@ +{%- comment -%} + Include as: {%- include_cached components/site_nav.html -%} + Depends on: site. + Results in: HTML for the site-nav. + Includes: + components/nav.html + Overwrites: + pages_top_size, collections_size, collection_entry, + collection_key, collection_value, collection. +{%- endcomment -%} + + \ No newline at end of file diff --git a/docs/_includes/js/custom.js b/docs/_includes/js/custom.js deleted file mode 100644 index a99a4d613..000000000 --- a/docs/_includes/js/custom.js +++ /dev/null @@ -1,12 +0,0 @@ -// window.matchMedia('(prefers-color-scheme: dark)') -// .addEventListener('change', event => { -// if (event.matches) { -// jtd.setTheme('dark'); -// } else { -// jtd.setTheme('light'); -// } -// }); - -// if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) { -// jtd.setTheme('dark'); -// } \ No newline at end of file diff --git a/docs/installation/AdvancedInstallation.md b/docs/_installation/AdvancedInstallation.md similarity index 100% rename from docs/installation/AdvancedInstallation.md rename to docs/_installation/AdvancedInstallation.md diff --git a/docs/installation/Helm.md b/docs/_installation/Helm.md similarity index 98% rename from docs/installation/Helm.md rename to docs/_installation/Helm.md index ee7eb45f0..915d41283 100644 --- a/docs/installation/Helm.md +++ b/docs/_installation/Helm.md @@ -161,7 +161,8 @@ release "splunk-enterprise-test" uninstalled ``` ```helm uninstall``` terminates all resources deployed by Helm including Persistent Volume Claims created for Splunk Enterprise resources. -Note: Helm by default does not cleanup Custom Resource Definitions and Persistent Volume Claims. Splunk Admin needs to manually clean them. +{: .note } +Helm by default does not cleanup Custom Resource Definitions and Persistent Volume Claims. Splunk Admin needs to manually clean them. ## Splunk Validated Architecture deployments diff --git a/docs/installation/Images.md b/docs/_installation/Images.md similarity index 100% rename from docs/installation/Images.md rename to docs/_installation/Images.md diff --git a/docs/installation/OpenShift.md b/docs/_installation/OpenShift.md similarity index 100% rename from docs/installation/OpenShift.md rename to docs/_installation/OpenShift.md diff --git a/docs/installation/Prerequisites.md b/docs/_installation/Prerequisites.md similarity index 100% rename from docs/installation/Prerequisites.md rename to docs/_installation/Prerequisites.md diff --git a/docs/installation/SplunkOperatorUpgrade.md b/docs/_installation/SplunkOperatorUpgrade.md similarity index 100% rename from docs/installation/SplunkOperatorUpgrade.md rename to docs/_installation/SplunkOperatorUpgrade.md diff --git a/docs/_sass/custom/custom.scss b/docs/_sass/custom/custom.scss new file mode 100644 index 000000000..685551ad3 --- /dev/null +++ b/docs/_sass/custom/custom.scss @@ -0,0 +1,4 @@ +.nav-category-divider { + padding: $sp-1; + // border-top: $border $border-color; + } \ No newline at end of file diff --git a/docs/troubleshooting/HealthCheck.md b/docs/_troubleshooting/HealthCheck.md similarity index 100% rename from docs/troubleshooting/HealthCheck.md rename to docs/_troubleshooting/HealthCheck.md diff --git a/docs/troubleshooting/K8SCollectors.md b/docs/_troubleshooting/K8SCollectors.md similarity index 100% rename from docs/troubleshooting/K8SCollectors.md rename to docs/_troubleshooting/K8SCollectors.md diff --git a/docs/pages/BiasLanguageMigration.md b/docs/pages/BiasLanguageMigration.md index 057bd45da..2ba2f3fd0 100644 --- a/docs/pages/BiasLanguageMigration.md +++ b/docs/pages/BiasLanguageMigration.md @@ -2,6 +2,7 @@ title: FAQ - Biased Language Migration nav_order: 100 #nav_exclude: true +nav_after_collections: true --- # FAQ - Biased Language Migration diff --git a/docs/pages/CONTRIBUTING.md b/docs/pages/CONTRIBUTING.md index 2e593543b..559371739 100644 --- a/docs/pages/CONTRIBUTING.md +++ b/docs/pages/CONTRIBUTING.md @@ -1,6 +1,7 @@ --- title: Contributing nav_order: 102 +nav_after_collections: true --- # Contributing to the Project diff --git a/docs/pages/ChangeLog.md b/docs/pages/ChangeLog.md index dc2391823..4a4f06e3e 100644 --- a/docs/pages/ChangeLog.md +++ b/docs/pages/ChangeLog.md @@ -1,6 +1,7 @@ --- title: Change Log nav_order: 101 +nav_after_collections: true --- # Splunk Operator for Kubernetes Change Log diff --git a/docs/pages/configuration.md b/docs/pages/configuration.md new file mode 100644 index 000000000..5d6a2eb36 --- /dev/null +++ b/docs/pages/configuration.md @@ -0,0 +1,7 @@ +--- +title: Configuration +has_children: true +has_toc: false +nav_order: 21 +nav_exclude: true +--- \ No newline at end of file diff --git a/docs/pages/index.md b/docs/pages/index.md index 260aa400f..d0be29813 100644 --- a/docs/pages/index.md +++ b/docs/pages/index.md @@ -100,7 +100,7 @@ kubectl delete standalone s1 The `Standalone` custom resource is just one of the resources the Splunk Operator provides. You can find more custom resources and the parameters they support on the [Custom Resource Guide](/configuration/CustomResources) page. For additional deployment examples, including Splunk Enterprise clusters, see the -[Configuring Splunk Enterprise Deployments](/configuration/examples) page. +[Configuring Splunk Enterprise Deployments](/configuration/Examples) page. For additional guidance on making Splunk Enterprise ports accessible outside of Kubernetes, see the [Configuring Ingress](/configuration/Ingress) page. diff --git a/docs/pages/installation.md b/docs/pages/installation.md new file mode 100644 index 000000000..a4e4a6783 --- /dev/null +++ b/docs/pages/installation.md @@ -0,0 +1,54 @@ +--- +title: Installation +has_children: true +has_toc: false +nav_order: 11 +nav_exclude: true +--- + +## Prerequisites +- Version >=1.5.0 of the Splunk Operator requires a Kubernetes cluster of version >=1.26.0. +- The Splunk Operator requires SmartStore to be configurted for indexed data storage. +- The use of Persistent Volume Claims requires that your cluster is configured to support one or more Kubernetes persistent Storage Classes + + +### Kubernetes Platform recommendations + +The Splunk Operator should work with any [CNCF certified distribution](https://www.cncf.io/certification/software-conformance/) of Kubernetes. We do not have platform recommendations, but this is a table of platforms that our developers, customers, and partners have used successfully with the Splunk Operator. + + + + + + +
Splunk Development & Testing Platforms Amazon Elastic Kubernetes Service (EKS), Google Kubernetes Engine (GKE)
Customer Reported Platforms Microsoft Azure Kubernetes Service (AKS), Red Hat OpenShift
Partner Tested Platforms HPE Ezmeral
Other Platforms CNCF certified distribution
+ +### Splunk Enterprise Version Compatibility + +Each Splunk Operator release has specific Splunk Enterprise compatibility requirements. Splunk Operator can support more than one version of Splunk Enterprise release. Before installing or upgrading the Splunk Operator, review the [release notes](https://github.com/splunk/splunk-operator/releases) to verify version compatibility with Splunk Enterprise releases. + + +### Hardware Resources Requirements +The resource guidelines for running production Splunk Enterprise instances in pods through the Splunk Operator are the same as running Splunk Enterprise natively on a supported operating system and file system. Refer to the Splunk Enterprise [Reference Hardware documentation](https://docs.splunk.com/Documentation/Splunk/latest/Capacity/Referencehardware) for additional details. We would also recommend following the same guidance on [Splunk Enterprise for disabling Transparent Huge Pages (THP)](https://docs.splunk.com/Documentation/Splunk/latest/ReleaseNotes/SplunkandTHP) for the nodes in your Kubernetes cluster. Please be aware that this may impact performance of other non-Splunk workloads. + + +#### Minimum Reference Hardware +Based on Splunk Enterprise [Reference Hardware documentation](https://docs.splunk.com/Documentation/Splunk/latest/Capacity/Referencehardware), a summary of the minimum reference hardware requirements is given below. + +| Standalone | Search Head / Search Head Cluster | Indexer Cluster | +| ---------- | ------- | ------- | +| _Each Standalone Pod: 12 Physical CPU Cores or 24 vCPU at 2Ghz or greater per core, 12GB RAM._| _Each Search Head Pod: 16 Physical CPU Cores or 32 vCPU at 2Ghz or greater per core, 12GB RAM._| _Each Indexer Pod: 12 Physical CPU cores, or 24 vCPU at 2GHz or greater per core, 12GB RAM._ | + + +### Storage guidelines +The Splunk Operator uses Kubernetes [Persistent Volume Claims](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) to store all of your Splunk Enterprise configuration ("$SPLUNK_HOME/etc" path) and event ("$SPLUNK_HOME/var" path) data. If one of the underlying machines fail, Kubernetes will automatically try to recover by restarting the Splunk Enterprise pods on another machine that is able to reuse the same data volumes. This minimizes the maintenance burden on your operations team by reducing the impact of common hardware failures to the equivalent of a service restart. +The use of Persistent Volume Claims requires that your cluster is configured to support one or more Kubernetes persistent [Storage Classes](https://kubernetes.io/docs/concepts/storage/storage-classes/). See the [Setting Up a Persistent Storage for Splunk](/configuration/StorageClass) page for more +information. + +### What Storage Type To Use? + +The Kubernetes infrastructure must have access to storage that meets or exceeds the recommendations provided in the Splunk Enterprise storage type recommendations at [Reference Hardware documentation - what storage type to use for a given role?](https://docs.splunk.com/Documentation/Splunk/latest/Capacity/Referencehardware#What_storage_type_should_I_use_for_a_role.3F) In summary, Indexers with SmartStore need NVMe or SSD storage to provide the necessary IOPs for a successful Splunk Enterprise environment. + + +### Splunk SmartStore Required +For production environments, we are requiring the use of Splunk SmartStore. As a Splunk Enterprise deployment's data volume increases, demand for storage typically outpaces demand for compute resources. [Splunk's SmartStore Feature](https://docs.splunk.com/Documentation/Splunk/latest/Indexer/AboutSmartStore) allows you to manage your indexer storage and compute resources in a ___cost-effective___ manner by scaling those resources separately. SmartStore utilizes a fast storage cache on each indexer node to keep recent data locally available for search and keep other data in a remote object store. Look into the [SmartStore Resource Guide](/configuration/SmartStore) document for configuring and using SmartStore through operator. diff --git a/docs/pages/support.md b/docs/pages/support.md index 59dd84cbc..0ee8e846e 100644 --- a/docs/pages/support.md +++ b/docs/pages/support.md @@ -1,6 +1,7 @@ --- title: Support nav_order: 90 +nav_after_collections: true --- ## Support Resources