diff --git a/docs/docs/getting-started/installation.mdx b/docs/docs/getting-started/installation.mdx index a13cdb33ff..7ca2df6942 100644 --- a/docs/docs/getting-started/installation.mdx +++ b/docs/docs/getting-started/installation.mdx @@ -30,9 +30,8 @@ You can configure Cloud-based Managed Tracetest by using the Tracetest CLI and T 1. [Sign in to Tracetest](https://app.tracetest.io/). 2. Create an [Organization](/concepts/organizations) and [Environment](/concepts/environments). -3. Copy the default [Tracetest Organization API Key/Token](/concepts/organization-tokens) from your Tracetest Organization Tokens page. (Or create a new token.) -4. Copy the Environment ID from your Tracetest Environment Settings page. -5. Configure the CLI with your Organization API Key/Token and Environment ID. +3. Copy your [Tracetest Organization API Key/Token and Environment ID](https://app.tracetest.io/retrieve-token). +4. Configure the CLI with your Organization API Key/Token and Environment ID. ```bash title="Terminal" tracetest configure -t --environment @@ -60,7 +59,7 @@ tracetest configure -t --environment Open Tracetest in a browser to this environment @@ -113,8 +112,6 @@ You can reach services running on your local machine using: > {`tracetest-agent: image: kubeshop/tracetest-agent - command: - - "--mode=verbose" environment: - TRACETEST_API_KEY= - TRACETEST_ENVIRONMENT_ID= @@ -125,9 +122,9 @@ You can reach services running on your local machine using: The Tracetest Agent is running in Docker and ready to accept traces. -gRPC: `http://:4317` +gRPC: `http://tracetest-agent:4317` -HTTP: `http://:4318/v1/traces` +HTTP: `http://tracetest-agent:4318/v1/traces` :::note Docker Network Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container. @@ -150,7 +147,7 @@ You can reach services running on your local machine using: language="text" title="Terminal" > -{`curl https://raw.githubusercontent.com/kubeshop/tracetest/main/k8s/agent/deploy-agent.sh | bash -s -- default `} +{`curl https://raw.githubusercontent.com/kubeshop/tracetest/main/k8s/agent/deploy-agent.sh | bash -s -- default --environment `} The Tracetest Agent is running in Kubernetes and ready to accept traces. @@ -235,10 +232,15 @@ flowchart TD ## Install Tracetest On-Prem -:::tip For Development Environment +:::note For Development Environment This installation is meant for testing purposes only. It uses self signed certificates, so your browser will show a warning about it. +::: + +:::tip For Production +For the Production-ready installation: -For the Production-ready installation, [view the official Helm chart readme](https://github.com/kubeshop/tracetest-cloud-charts/blob/main/README.md). +- [View the official Helm chart readme](https://github.com/kubeshop/tracetest-cloud-charts/blob/main/README.md). +- [View the official installation docs](/install/helm). ::: 1. Install [Helm](https://helm.sh/) and [kind](https://kind.sigs.k8s.io/) on your machine. Clone the official Tracetest Helm chart. @@ -248,7 +250,7 @@ git clone https://github.com/kubeshop/tracetest-cloud-charts.git cd ./tracetest-cloud-charts ``` -2. Request a **licence key, [here](https://tracetest.io/on-prem-installation)**. +2. Request a **license key, [here](https://tracetest.io/on-prem-installation)**. 3. Run the setup script with a demo. Add your license key when you get prompted. diff --git a/docs/docs/install/cli.mdx b/docs/docs/install/cli.mdx new file mode 100644 index 0000000000..64b6ab8ac7 --- /dev/null +++ b/docs/docs/install/cli.mdx @@ -0,0 +1,62 @@ +--- +id: cli +title: Install with CLI +description: Installation and deployment instructions for using the Tracetest CLI to deploy a Tracetest Agent and use the Cloud-based managed Tracetest Control Plane / Dashboard. +hide_table_of_contents: true +keywords: + - tracetest + - tracetest cli install + - tracetest cloud install + - tracetest agent install + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg +--- + +import GtagInstallCliTabs from '@site/src/components/GtagInstallCliTabs'; + +This guide explains how to configure Cloud-based managed Tracetest with the Tracetest CLI and install a Tracetest Agent in your local development environment. This deployment uses the Cloud-based managed Tracetest Control Plane and Dashboard. + +## Prerequisites + +- [Sign in to Tracetest](https://app.tracetest.io/) and retrieve your [Tracetest Organization API Key/Token and Environment ID](https://app.tracetest.io/retrieve-token). + +## Install the Tracetest CLI + + + +Configure the CLI to access your Cloud-based managed Tracetest account. + +```bash title="Terminal" +tracetest configure -t --environment +``` + +## Install the Tracetest Agent Locally + +[Tracetest Agent](/concepts/agent) runs as a standalone process. + +```bash title="Terminal" +tracetest start --api-key --environment +``` + +```bash title="Expected Output" +Tracetest start launches a lightweight agent. It enables you to run tests and collect traces with Tracetest. +Once started, Tracetest Agent exposes OTLP ports 4317 and 4318 to ingest traces via gRCP and HTTP. + + INFO Running in desktop mode... + INFO Starting Agent with name... +Agent is started! Leave the terminal open so tests can be run and traces gathered from this environment. +You can: +> Open Tracetest in a browser to this environment + (Experimental) Open Dashboard + Stop this agent +``` + +Tracetest Agent runs tests and ingests traces. It exposes OTLP ports `4317` (gRPC) and `4318` (HTTP) for trace ingestion. In this example you can trigger tests against apps running in your local environment on `localhost` and export traces from your local apps to `localhost` as well. + +To ingest traces in this example with Tracetest Agent use these URLs: + +- gRPC: `http://localhost:4317` +- HTTP: `http://localhost:4318/v1/traces` diff --git a/docs/docs/install/deployment-architecture.mdx b/docs/docs/install/deployment-architecture.mdx new file mode 100644 index 0000000000..769482908c --- /dev/null +++ b/docs/docs/install/deployment-architecture.mdx @@ -0,0 +1,241 @@ +--- +id: deployment-architecture +title: Deployment Architecture +description: bla +keywords: + - tracetest + - trace-based testing + - opentelemetry store demo + - open telemetry demo + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_Thumbnail_28_ugy2yy.png +--- + +Tracetest contains two parts: + +- A Control Plane which includes the Dashboard, Database + Storage, RBAC, etc. +- An Agent running in your environment that runs tests and ingests traces. + +You can deploy Tracetest in two ways. + +- Deploy Tracetest Agent and use the Cloud-based managed Control Plane. +- Deploy both Tracetest Agent and Control Plane On-Prem. + +## Enterprise Self-hosted Tracetest + +With Enterprise self-hosted Tracetest you deploy both the control plane and agent in your own infrastructure. + +To deploy Enterprise self-hosted Tracetest follow the [installing with Helm guide](/install/helm). + +## Architecture + +Enterprise self-hosted Tracetest is composed of multiple services: + +- **Frontend**: the WebUI used to interact with Tracetest, allowing users to [create and manage tests](https://docs.tracetest.io/web-ui/creating-tests). +- **Cloud/Core API**: APIs that are called directly by the Frontend, the Tracetest CLI and the Tracetest Agent to perform operations on the systems, like creating and running tests. +- **Ory Ecosystem**: Tracetest relies on the [Ory Ecosystem](https://www.ory.sh/) for authentication and authorization. This includes [Ory Kratos](https://www.ory.sh/kratos/docs/), [Ory Keto](https://www.ory.sh/keto/docs/), and [Ory Oathkeeper](https://www.ory.sh/oathkeeper/docs/). +- **Tracetest Workers**: A set of workers that manage the test execution. +- **Nats**: An instance of [nats.io](https://nats.io/) uses a message broker that works as a communication bridge between the different services. +- **Agent**: Triggers tests and ingests traces. + +```mermaid +graph LR + Postgres[("Postgres")] + Mongo[("Mongo")] + Nats + SMTPServer["SMTP Server"] + Ory["Ory Ecosystem\n(AuthZ / AuthN)"] + TracetestAPI["Cloud/Core\nAPI"] + TracetestWorkers["Tracetest\nWorkers"] + TracetestFrontend["Frontend"] + TracetestAgentAPI["Agent\nAPI"] + TracetestAgentIngestAPI["Trace\nIngest API"] + User + + User --> TracetestFrontend + User --> Ory + User --> TracetestAPI + + subgraph Control Plane + TracetestFrontend --> TracetestAPI + + TracetestAPI --> Nats + TracetestWorkers --> Nats + + TracetestFrontend --> Ory + TracetestAPI --> Ory + end + + subgraph Agent + TracetestAgentAPI --> TracetestAPI + TracetestAgentIngestAPI --> TracetestAgentAPI + end + + subgraph ExternalDependencies["External Deps"] + TracetestAPI --> SMTPServer + Ory --> Postgres + TracetestAPI --> Postgres + TracetestAPI --> Mongo + end + +``` + +## Prerequisites + +Tracetest expects some preconditions in the environment where it runs. + +### DNS + +Tracetest needs to be accessible from a DNS route. We recommend you to use an exposed Traefik `IngressRoute`. + +This requires a DNS-resolvable name. You can use a public DNS, an intranet DNS, or even host file based, +as long as clients can resolve the host names to the correct IPs. + +You can choose any hostname you want. This Helm repo imposes no limitation on this. + +If you choose to use a DNS resolving mechanism that is not available within the Kubernetes cluster where Tracetest runs, +you can configure the cluster's CoreDNS to point the selected hostname to the Traefik Service. We provide a [script for this](https://github.com/kubeshop/tracetest-cloud-charts/blob/main/scripts/coredns_config.sh). + +If you want to use managed agents and send OpenTelemetry trace data to them from outside the cluster, you need to set a wildcard subdomain. + +:::tip Does this mean that Tracetest will be accessible from the internet? +Not neccesarily. By default, most cloud providers will automatically map LoadBalancer services to public IPs. + +If you want to make your installation only availble within an intranet or similarly private environment check how to configure Private IPs with your cloud provider docs. +::: + +:::note Example +Your main domain is `tracetest.mydomain.com`. You need to setup `tracetest.mydomain.com` and `*.tracetest.mydomain.com` to the LoadBalancer IP. +::: + +### Cert Manager + +Tracetest uses cert-manager to create sign certificates for JWT tokens and SSL certificates for Ingress. + +```bash title="Terminal" +helm repo add jetstack https://charts.jetstack.io --force-update +helm upgrade --install \ + cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --create-namespace \ + --version v1.15.0 \ + --set crds.enabled=true +``` + +Cert Manager defines Issuers. If you have existing Issuers that you want to use, you can configure them in `values.yaml`. + +In order to have a valid certificate, `cert-manager` requires you to provide proof of ownership of the DNS domain that you are claiming. You can see how to do that in the [Issuers documentation](https://cert-manager.io/docs/configuration/issuers/). + +While it is not recommended in a production environment, it is possible by creating a SelfSigned Issuer and create self-signed certificates. With self-signed certificates you will see warnings on the browser when accessing your Tracetest OnPrem instance Web UI. + +```bash title="Terminal" +# Create a self signed certificate + +cat < TracetestAgentAPI + end + + subgraph Control Plane + TracetestAgentAPI --> TracetestControlPlane + end + + User --> TracetestControlPlane + +``` + +## Prerequisites + +- [Sign in to Tracetest](https://app.tracetest.io/) and retrieve your [Tracetest Organization API Key/Token and Environment ID](https://app.tracetest.io/retrieve-token). diff --git a/docs/docs/install/docker.mdx b/docs/docs/install/docker.mdx new file mode 100644 index 0000000000..2ac7c7e281 --- /dev/null +++ b/docs/docs/install/docker.mdx @@ -0,0 +1,65 @@ +--- +id: docker +title: Install with Docker +description: Installation and deployment instructions for using Docker to deploy a Tracetest Agent and use the Cloud-based managed Tracetest Control Plane / Dashboard. +hide_table_of_contents: true +keywords: + - tracetest + - tracetest cli install + - tracetest cloud install + - tracetest agent install + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg +--- + +This guide explains how to install a Tracetest Agent in your Docker (and Docker Compose) environment. This deployment uses the Cloud-based managed Tracetest Control Plane and Dashboard. + +## Prerequisites + +- Install [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/). +- [Sign in to Tracetest](https://app.tracetest.io/) and retrieve your [Tracetest Organization API Key/Token and Environment ID](https://app.tracetest.io/retrieve-token). + + +## Install the Tracetest Agent with Docker + +[Tracetest Agent](/concepts/agent) runs as a Docker container. + +```bash title="Terminal" +docker run + -p 4317:4317 + -p 4318:4318 + -e TRACETEST_API_KEY="" + -e TRACETEST_ENVIRONMENT_ID="" + kubeshop/tracetest-agent +``` + +## Install the Tracetest Agent with Docker Compose + +[Tracetest Agent](/concepts/agent) runs as a Docker Compose service. + +```yaml title="docker-compose.yaml" +tracetest-agent: + image: kubeshop/tracetest-agent + environment: + - TRACETEST_API_KEY= + - TRACETEST_ENVIRONMENT_ID= + ports: + - 4317:4317 + - 4318:4318 +``` + +The Tracetest Agent is running in a Docker network and can run tests and ingest traces. It exposes OTLP ports `4317` (gRPC) and `4318` (HTTP) for trace ingestion. + +To ingest traces in this example with Tracetest Agent use these URLs: + +- gRPC: `http://tracetest-agent:4317` +- HTTP: `http://tracetest-agent:4318/v1/traces` + +:::note Docker Network +Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container. Add Tracetest Agent to the same network and use service name mapping. *Example: Instead of running an app on `localhost:8080`, add it to your Docker Compose file, connect it to the same network as your Tracetest Agent service, and use `:8080` in the URL field when creating a test.* + +To run tests against apps running on your local machine, [view this guide](/install/cli). +::: \ No newline at end of file diff --git a/docs/docs/install/gcp.mdx b/docs/docs/install/gcp.mdx new file mode 100644 index 0000000000..137056f4cc --- /dev/null +++ b/docs/docs/install/gcp.mdx @@ -0,0 +1,167 @@ +--- +id: gcp +title: Install in GCP +description: Get started by installing Tracetest in your GCP cluster with GKE. +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg +--- + +Installation and deployment instructions for using Helm to deploy Enterprise self-hosted Tracetest in GCP (GKE) and use the On-Prem Tracetest Control Plane/Dashboard. + +## Prerequisites + +- A Kubernetes cluster running on GKE ([installation instructions](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-an-autopilot-cluster)). +- Traefik installed in your cluster ([installation instructions](https://doc.traefik.io/traefik/getting-started/install-traefik/)). +- A Cert Manager installed in your cluster ([installation instructions](https://cert-manager.io/docs/installation/kubernetes/)). +- A Tracetest license key. If you don't have one, you can request a trial license key [here](https://tracetest.io/on-prem-installation). +- Install [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl). +- Install [Helm](https://helm.sh/). + +## Install Tracetest On-Premises in GCP (GKE) with Helm + +The [main chart for this repository is called `tracetest-onprem`](https://github.com/kubeshop/tracetest-cloud-charts/blob/main/README.md) and contains all components necessary to run Enterprise self-hosted Tracetest on-premises in a cluster that fits the [deployment architecture](/install/deployment-architecture). + +### Cert Manager + +Make sure that you have a [Cert Manager](https://cert-manager.io) installed in your cluster with a valid issuer. If you don't have one, you can follow the [cert-manager installation guide](https://cert-manager.io/docs/installation/) or use the following command to install it: + +```bash title="Terminal" +# create namespace for cert-manager in your cluster +kubectl create namespace cert-manager + +# add the jetstack repository to helm +helm repo add jetstack https://charts.jetstack.io --force-update + +# install cert-manager, setting the CRDs and leader election namespace (needed for GKE) +helm install cert-manager jetstack/cert-manager \ + --namespace cert-manager \ + --version v1.15.0 \ + --set crds.enabled=true \ + --set global.leaderElection.namespace=cert-manager +``` + +### Traefik + +Also, you will need to have a Traefik proxy, that will handle all connections to the Tracetest services. You can install Traefik by creating a `values-traefik.yaml` file with the following content: + +```yaml title="values-traefik.yaml" +dnsNames: + - "tracetest.localdev" # add here your DNS domain to access Tracetest + +tls: + issuerRef: + ... # add here your issuer reference + +providers: + kubernetesCRD: + enabled: true + +service: + type: NodePort + +ports: + websecure: + port: 30000 + exposedPort: 30000 + nodePort: 30000 + protocol: TCP + tls: + enabled: true + http2: + maxConcurrentStreams: 250 +``` + +And then run the following commands: + +```sh title="Terminal" +# create namespace for traefik in your cluster +kubectl create namespace traefik + +# add traefik charts in your machine +helm repo add traefik https://helm.traefik.io/traefik --force-update + +# install traefik in your cluster +helm install traefik traefik/traefik \ + --namespace traefik \ + --values values-traefik.yaml +``` + +### DNS + +After that, you will create a `values.yaml` file that defines what is the DNS domain that you will use to access the Tracetest services and the connection details for Postgres and MongoDB. +You can see more details about the `values.yaml` file [here](https://github.com/kubeshop/tracetest-cloud-charts/blob/main/charts/tracetest-onprem/values.yaml). + +You can use the following template to create your `values.yaml` file, where we are using the domain `tracetest.localdev` as the DNS, `tracetest-postgres-postgresql.external` as the Postgres and `tracetest-dependencies-mongodb.external` MongoDB server: + +```yaml title="values.yaml" +global: + urls: + protocol: &protocol "https" + port: &port "30000" + rootDomain: &rootDomain "tracetest.localdev" + cookieDomain: *rootDomain + + web: + protocol: *protocol + hostname: *rootDomain + port: *port + + api: + protocol: *protocol + hostname: *rootDomain + port: *port + + auth: + protocol: *protocol + hostname: *rootDomain + port: *port + + agents: + domain: *rootDomain + port: *port + + controlPlane: + protocol: *protocol + hostname: *rootDomain + port: *port + + postgresql: + auth: + host: "tracetest-postgres-postgresql.external" + username: "tracetest" + password: "tracetest" + database: "tracetest" + + mongodb: + auth: + protocol: "mongodb" + host: "tracetest-dependencies-mongodb.external" + username: "tracetest" + password: "tracetest" + database: "tracetest" + options: + retryWrites: "true" + authSource: admin +``` + +### Helm Install +And finally, run the `helm install` command with your license key and the `values.yaml` file: + +```sh +# create namespace for tracetest cloud in your cluster +kubectl create namespace tracetestcloud + +# add tracetest cloud charts in your machine +helm repo add tracetestcloud https://kubeshop.github.io/tracetest-cloud-charts --force-update + +# and then install tracetest cloud in your cluster +helm install my-tracetest-cloud tracetestcloud/tracetest-onprem \ + --namespace tracetestcloud \ + --set global.licenseKey= \ + --values values.yaml +``` diff --git a/docs/docs/install/helm.mdx b/docs/docs/install/helm.mdx new file mode 100644 index 0000000000..2bbd106f1b --- /dev/null +++ b/docs/docs/install/helm.mdx @@ -0,0 +1,229 @@ +--- +id: helm +title: Install with Helm +hide_table_of_contents: false +description: Installation and deployment instructions for using Helm to deploy Enterprise self-hosted Tracetest and use the On-Prem Tracetest Control Plane / Dashboard. +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg +--- + +Installation and deployment instructions for using Helm to deploy Enterprise self-hosted Tracetest and use the On-Prem Tracetest Control Plane/Dashboard. + +## Prerequisites + +- A running Kubernetes cluster. +- A Tracetest license key. If you don't have one, you can request a trial license key [here](https://tracetest.io/on-prem-installation). +- Install [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl). +- Install [Helm](https://helm.sh/). + +## Install Tracetest On-Premises with Helm + +The [main chart for this repository is called `tracetest-onprem`](https://github.com/kubeshop/tracetest-cloud-charts/blob/main/README.md) and contains all components necessary to run Enterprise self-hosted Tracetest on-premises in a cluster that fits the [deployment architecture](/install/deployment-architecture). + +```bash title="Terminal" +helm repo add tracetestcloud https://kubeshop.github.io/tracetest-cloud-charts --force-update + +helm install my-tracetest tracetestcloud/tracetest-onprem \ + --set global.licenseKey= \ + --values values.yaml +``` + +## Configuration + +Configure the Helm installation with the `values.yaml` file. View the [`values.yaml` default values, here.](https://github.com/kubeshop/tracetest-cloud-charts/blob/main/charts/tracetest-onprem/values.yaml) + +
+ + Click to expand the `values.yaml` default values. + + +```yaml +global: + # License Key provided by Tracetest team to run this instance. Default: `""` + licenseKey: "" + + # This value defines if clients should expect a valid SSL certificate from the server. If you are using a self-signed certificate, you should set this to false. Default: `true` + validCertificate: true + + # Pull secrets name used to fetch images from a private registry if needed. If set empty, this chart will use the public registry. For more details see: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ Default: `""` + imagePullSecret: "" + # Registry name used to fetch images. If set empty, this chart will use the public registry. For more details see: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ Default: `""` + tracetestImageRegistry: "" + + sso: + google: + # Google OAuth2 client ID. You can get these from the Google Developer Console. Default: `""` + clientID: "" + # Google OAuth2 secret. You can get these from the Google Developer Console. Default: `""` + clientSecret: "" + github: + # Github OAuth2 client ID. You can get these from the Github Developer Console. Default: `"example client ID"` + clientID: "Ov23li8WMwQlvjFNNiCy" + # Github OAuth2 secret. You can get these from the Github Developer Console. Default: `"example client secret"` + clientSecret: "e317c15e43909757d1e75e78373d130c374f6601" + + # If you don't want to use the default NATS server, you can specify your own NATS server here + # natsEndpointOverride: "://nats:4222" + + postgresql: + auth: + # Postgres host address. Default: `""` + host: "" + # Postgres username that Tracetest APIs will use. Default: `""` + username: "" + # Postgres password that Tracetest APIs will use. Default: `""` + password: "" + # Postgres database name for Tracetest OnPrem. Default: `"tracetest"` + database: "tracetest" + # Postgres port. Default: `"5432"` + port: "5432" + + mongodb: + auth: + # MongoDB connection protocol. Default: `"mongodb"` + protocol: "mongodb" + # MongoDB host address. Default: `""` + host: "" + # MongoDB username that Tracetest APIs will use. Default: `""` + username: "" + # MongoDB password that Tracetest APIs will use. Default: `""` + password: "" + # MongoDB database name for Tracetest OnPrem. Default: `"tracetest"` + database: "" + # MongoDB connection options as a key-value object. Default: `"{}"` + options: {} + + + # URLs section with addresses used by clients to connect to the Tracetest OnPrem instance + urls: + protocol: &protocol "https" + port: &port "30000" + rootDomain: &rootDomain "tracetest.localdev" + cookieDomain: *rootDomain + + web: + protocol: *protocol + hostname: *rootDomain + port: *port + path: "/" + + api: + protocol: *protocol + hostname: *rootDomain + port: *port + path: "/api" + + auth: + protocol: *protocol + hostname: *rootDomain + port: *port + path: "/auth" + + agents: + domain: *rootDomain + port: *port + + controlPlane: + protocol: *protocol + hostname: *rootDomain + port: *port + path: "/" + +nats: + enabled: true + + config: + jetstream: + enabled: true + fileStore: + enabled: true + dir: /data + pvc: + enabled: true + size: 10Gi + memoryStore: + enabled: true + maxSize: 1Gi + + natsBox: + container: + env: + # different from k8s units, suffix must be B, KiB, MiB, GiB, or TiB + # should be ~90% of memory limit + GOMEMLIMIT: 900MiB + merge: + # recommended limit is at least 2 CPU cores and 8Gi Memory for production JetStream clusters + resources: + requests: + cpu: 250m # one entire CPU + memory: 1Gi + limits: + memory: 1Gi +``` + +
+ +
+ + Click to expand the `values.yaml` with SSO and a database. + + +```yaml +global: + validCertificate: false # defines if the certificate is generated by an external issuer of if the self-signed issuer is used + + urls: + protocol: &protocol "https" + port: &port "30000" + rootDomain: &rootDomain "tracetest.mydomain.com" # DNS that the users will use to access the Tracetest + cookieDomain: *rootDomain + + web: + protocol: *protocol + hostname: *rootDomain + port: *port + + api: + protocol: *protocol + hostname: *rootDomain + port: *port + + auth: + protocol: *protocol + hostname: *rootDomain + port: *port + + agents: + domain: *rootDomain + port: *port + + controlPlane: + protocol: *protocol + hostname: *rootDomain + port: *port + + postgresql: + auth: + host: "path.to.my.postgres.instance" + username: "some-pg-user" + password: "some-pg-password" + database: "tracetest" + + mongodb: + auth: + protocol: "mongodb" + host: "path.to.my.mongodb.instance" + username: "some-mongo-user" + password: "some-mongo-password" + database: "tracetest" + options: + retryWrites: "true" + authSource: admin +``` + +
diff --git a/docs/docs/install/kubernetes.mdx b/docs/docs/install/kubernetes.mdx new file mode 100644 index 0000000000..8c5284d2ce --- /dev/null +++ b/docs/docs/install/kubernetes.mdx @@ -0,0 +1,53 @@ +--- +id: kubernetes +title: Install with Kubernetes +description: Installation and deployment instructions for using Kubernetes deploy a Tracetest Agent and use the Cloud-based managed Tracetest Control Plane / Dashboard. +hide_table_of_contents: true +keywords: + - tracetest + - tracetest cli install + - tracetest cloud install + - tracetest agent install + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg +--- + +This guide explains how to install a Tracetest Agent in your Kubernetes environment. This deployment uses the Cloud-based managed Tracetest Control Plane and Dashboard. + +## Prerequisites + +- A running Kubernetes cluster. +- Install [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl). +- [Sign in to Tracetest](https://app.tracetest.io/) and retrieve your [Tracetest Organization API Key/Token and Environment ID](https://app.tracetest.io/retrieve-token). + + +## Install the Tracetest Agent with Kubernetes + +[Tracetest Agent](/concepts/agent) runs as a Kubernetes Daemonset. + +```bash title="Terminal" +curl https://raw.githubusercontent.com/kubeshop/tracetest/main/k8s/agent/deploy-agent.sh | bash -s -- default --environment +``` + +The Tracetest Agent is running in Kubernetes and ready to accept traces. + +gRPC: `http://:4317` + +HTTP: `http://:4318/v1/traces` + +:::note K8s Network +Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container. + +To run tests against apps running on your local machine you have two options: + +1. Run the Tracetest Agent locally with the `tracetest start` command. +2. Add the Tracetest Agent to the same network and use service name mapping. *Example: Instead of running an app on `localhost:8080`, add it to your Docker Compose file, connect it to the same network as your Tracetest Agent service, and use `:8080` in the URL field when creating a test.* + +You can reach services running on your local machine using: + +- Linux (docker version < 20.10.0): `172.17.0.1:8080` +- MacOS (docker version >= 18.03) and Linux (docker version >= 20.10.0): `host.docker.internal:8080` +::: diff --git a/docs/docs/install/overview.mdx b/docs/docs/install/overview.mdx new file mode 100644 index 0000000000..2cc26e55d9 --- /dev/null +++ b/docs/docs/install/overview.mdx @@ -0,0 +1,32 @@ +--- +id: overview +title: Overview +description: Learn how to install Tracetest in your infrastructure. Pick between Cloud-based managed and On-prem self-hosted options. +hide_table_of_contents: false +keywords: + - tracetest + - tracetest installation + - tracetest installation overview + - trace-based testing installation +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg +--- + +:::info Prerequisites +- Access to an app that is exporting OpenTelemetry distributed traces. +- If you don't have one, [**try our live demos**](/getting-started/try-live-demos) to evaluate Tracetest. +- Or, read our [guide how to configure OpenTelemetry](/getting-started/no-otel) yourself. +::: + +Tracetest supports two deployment models. + +- [Cloud-based managed](https://app.tracetest.io/) +- [Enterprise self-hosted](https://tracetest.io/on-prem-installation) + +With both options Tracetest Agents run in your infrastructure on the same network as your application under test. Tracetest Agents are test runners and trace ingestors. You can choose to run the control plane / dashboard self-hosted or let us manage it in Cloud-based managed Tracetest, it's up to you. Check out the [deployment architecture](/install/deployment-architecture) to learn more. + +You can install Tracetest by using one of the following deployment options: + +- Use the [Tracetest CLI](/install/cli) for an out-of-the-box experience with Cloud-based managed Tracetest. +- Use [Docker](/install/docker) to run Tracetest Agent with with Cloud-based managed Tracetest. +- Use [Kubernetes](/install/kubernetes) to run Tracetest Agent with with Cloud-based managed Tracetest. +- Use the [Tracetest Helm Chart](/install/helm) to customize your deployment with Enterprise self-hosted Tracetest. diff --git a/docs/sidebars.js b/docs/sidebars.js index 73ef08691a..b8103b2548 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -538,6 +538,62 @@ const sidebars = { }, ], }, + { + type: "html", + value: "
", + }, + { + type: "category", + label: "Installing", + link: { + type: "doc", + id: "install/overview", + }, + items: [ + { + type: "category", + label: "Cloud-based managed", + items: [ + { + type: "doc", + id: "install/cli", + label: "Install with CLI", + }, + { + type: "doc", + id: "install/docker", + label: "Install with Docker", + }, + { + type: "doc", + id: "install/kubernetes", + label: "Install with Kubernetes", + }, + ], + }, + { + type: "category", + label: "Enterprise self-hosted", + items: [ + { + type: "doc", + id: "install/helm", + label: "Install with Helm", + }, + { + type: "doc", + id: "install/gcp", + label: "Install in GCP", + }, + ], + }, + { + type: "doc", + id: "install/deployment-architecture", + label: "Deployment Architecture", + }, + ], + }, { type: "category", label: "Concepts", @@ -552,11 +608,6 @@ const sidebars = { id: "concepts/open-source-vs-commercial-features", label: "Open Source vs Commercial Features", }, - // { - // type: "doc", - // id: "concepts/what-is-tracing", - // label: "What is tracing", - // }, { type: "doc", id: "concepts/agent", @@ -751,7 +802,6 @@ const sidebars = { }, ], }, - { type: "category", label: "Using Tracetest",