From f8fb8866a509bb9a4e55695c1b6a428d2f19499d Mon Sep 17 00:00:00 2001 From: Razz4780 Date: Fri, 3 Nov 2023 16:30:21 +0100 Subject: [PATCH] Config docs --- mirrord-schema.json | 38 ++++++++++++++++++++--- mirrord/config/src/feature.rs | 2 +- mirrord/config/src/feature/copy_target.rs | 17 +++++++++- mirrord/config/src/lib.rs | 6 +++- 4 files changed, 55 insertions(+), 8 deletions(-) diff --git a/mirrord-schema.json b/mirrord-schema.json index 996df2194ec..25dd0c33793 100644 --- a/mirrord-schema.json +++ b/mirrord-schema.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "title": "LayerFileConfig", - "description": "mirrord allows for a high degree of customization when it comes to which features you want to enable, and how they should function.\n\nAll of the configuration fields have a default value, so a minimal configuration would be no configuration at all.\n\nThe configuration supports templating using the [Tera](https://keats.github.io/tera/docs/) template engine. Currently we don't provide additional values to the context, if you have anything you want us to provide please let us know.\n\nTo help you get started, here are examples of a basic configuration file, and a complete configuration file containing all fields.\n\n### Basic `config.json` {#root-basic}\n\n```json { \"target\": \"pod/bear-pod\", \"feature\": { \"env\": true, \"fs\": \"read\", \"network\": true } } ```\n\n### Basic `config.json` with templating {#root-basic-templating}\n\n```json { \"target\": \"{{ get_env(name=\"TARGET\", default=\"pod/fallback\") }}\", \"feature\": { \"env\": true, \"fs\": \"read\", \"network\": true } } ```\n\n### Complete `config.json` {#root-complete}\n\nDon't use this example as a starting point, it's just here to show you all the available options. ```json { \"accept_invalid_certificates\": false, \"skip_processes\": \"ide-debugger\", \"pause\": false, \"target\": { \"path\": \"pod/bear-pod\", \"namespace\": \"default\" }, \"connect_tcp\": null, \"agent\": { \"log_level\": \"info\", \"namespace\": \"default\", \"image\": \"ghcr.io/metalbear-co/mirrord:latest\", \"image_pull_policy\": \"IfNotPresent\", \"image_pull_secrets\": [ { \"secret-key\": \"secret\" } ], \"ttl\": 30, \"ephemeral\": false, \"communication_timeout\": 30, \"startup_timeout\": 360, \"network_interface\": \"eth0\", \"flush_connections\": true }, \"feature\": { \"env\": { \"include\": \"DATABASE_USER;PUBLIC_ENV\", \"exclude\": \"DATABASE_PASSWORD;SECRET_ENV\", \"override\": { \"DATABASE_CONNECTION\": \"db://localhost:7777/my-db\", \"LOCAL_BEAR\": \"panda\" } }, \"fs\": { \"mode\": \"write\", \"read_write\": \".+\\.json\" , \"read_only\": [ \".+\\.yaml\", \".+important-file\\.txt\" ], \"local\": [ \".+\\.js\", \".+\\.mjs\" ] }, \"network\": { \"incoming\": { \"mode\": \"steal\", \"http_header_filter\": { \"filter\": \"host: api\\..+\", \"ports\": [80, 8080] }, \"port_mapping\": [[ 7777, 8888 ]], \"ignore_localhost\": false, \"ignore_ports\": [9999, 10000] }, \"outgoing\": { \"tcp\": true, \"udp\": true, \"filter\": { \"local\": [\"tcp://1.1.1.0/24:1337\", \"1.1.5.0/24\", \"google.com\", \":53\"] }, \"ignore_localhost\": false, \"unix_streams\": \"bear.+\" }, \"dns\": false }, }, \"operator\": true, \"kubeconfig\": \"~/.kube/config\", \"sip_binaries\": \"bash\", \"telemetry\": true, \"kube_context\": \"my-cluster\" } ```\n\n# Options {#root-options}", + "description": "mirrord allows for a high degree of customization when it comes to which features you want to enable, and how they should function.\n\nAll of the configuration fields have a default value, so a minimal configuration would be no configuration at all.\n\nThe configuration supports templating using the [Tera](https://keats.github.io/tera/docs/) template engine. Currently we don't provide additional values to the context, if you have anything you want us to provide please let us know.\n\nTo help you get started, here are examples of a basic configuration file, and a complete configuration file containing all fields.\n\n### Basic `config.json` {#root-basic}\n\n```json { \"target\": \"pod/bear-pod\", \"feature\": { \"env\": true, \"fs\": \"read\", \"network\": true } } ```\n\n### Basic `config.json` with templating {#root-basic-templating}\n\n```json { \"target\": \"{{ get_env(name=\"TARGET\", default=\"pod/fallback\") }}\", \"feature\": { \"env\": true, \"fs\": \"read\", \"network\": true } } ```\n\n### Complete `config.json` {#root-complete}\n\nDon't use this example as a starting point, it's just here to show you all the available options. ```json { \"accept_invalid_certificates\": false, \"skip_processes\": \"ide-debugger\", \"pause\": false, \"target\": { \"path\": \"pod/bear-pod\", \"namespace\": \"default\" }, \"connect_tcp\": null, \"agent\": { \"log_level\": \"info\", \"namespace\": \"default\", \"image\": \"ghcr.io/metalbear-co/mirrord:latest\", \"image_pull_policy\": \"IfNotPresent\", \"image_pull_secrets\": [ { \"secret-key\": \"secret\" } ], \"ttl\": 30, \"ephemeral\": false, \"communication_timeout\": 30, \"startup_timeout\": 360, \"network_interface\": \"eth0\", \"flush_connections\": true }, \"feature\": { \"env\": { \"include\": \"DATABASE_USER;PUBLIC_ENV\", \"exclude\": \"DATABASE_PASSWORD;SECRET_ENV\", \"override\": { \"DATABASE_CONNECTION\": \"db://localhost:7777/my-db\", \"LOCAL_BEAR\": \"panda\" } }, \"fs\": { \"mode\": \"write\", \"read_write\": \".+\\.json\" , \"read_only\": [ \".+\\.yaml\", \".+important-file\\.txt\" ], \"local\": [ \".+\\.js\", \".+\\.mjs\" ] }, \"network\": { \"incoming\": { \"mode\": \"steal\", \"http_header_filter\": { \"filter\": \"host: api\\..+\", \"ports\": [80, 8080] }, \"port_mapping\": [[ 7777, 8888 ]], \"ignore_localhost\": false, \"ignore_ports\": [9999, 10000] }, \"outgoing\": { \"tcp\": true, \"udp\": true, \"filter\": { \"local\": [\"tcp://1.1.1.0/24:1337\", \"1.1.5.0/24\", \"google.com\", \":53\"] }, \"ignore_localhost\": false, \"unix_streams\": \"bear.+\" }, \"dns\": false, \"copy_target\": { \"enabled\": true, \"scale_down\": false } }, }, \"operator\": true, \"kubeconfig\": \"~/.kube/config\", \"sip_binaries\": \"bash\", \"telemetry\": true, \"kube_context\": \"my-cluster\" } ```\n\n# Options {#root-options}", "type": "object", "properties": { "accept_invalid_certificates": { @@ -388,6 +388,20 @@ } ] }, + "CopyTargetFileConfig": { + "description": "Allows the user to target a pod created dynamically from the orignal [`target`](#target). The new pod inherits most of the original target's specification, e.g. labels.\n\n```json { \"feature\": { \"copy_target\": { \"scale_down\": true } } } ```", + "type": "object", + "properties": { + "scale_down": { + "title": "feature.copy_target.scale_down {#feature-copy_target-scale_down}", + "description": "If this option is set and [`target`](#target) is a deployment, mirrord will scale it down by 1 for the time the copied pod is alive.", + "type": [ + "boolean", + "null" + ] + } + } + }, "DeploymentTarget": { "description": " Mirror the deployment specified by [`DeploymentTarget::deployment`].", "type": "object", @@ -454,11 +468,15 @@ "type": "object", "properties": { "copy_target": { - "title": "feature.copy_target {#feature-copy-target}", + "title": "feature.copy_target {#feature-copy_target}", "description": "Creates a new copy of the target. mirrord will use this copy instead of the original target (e.g. intercept network traffic). This feature requires a [mirrord operator](https://mirrord.dev/docs/teams/introduction/).", - "type": [ - "boolean", - "null" + "anyOf": [ + { + "$ref": "#/definitions/ToggleableConfig_for_CopyTargetFileConfig" + }, + { + "type": "null" + } ] }, "env": { @@ -1064,6 +1082,16 @@ } ] }, + "ToggleableConfig_for_CopyTargetFileConfig": { + "anyOf": [ + { + "type": "boolean" + }, + { + "$ref": "#/definitions/CopyTargetFileConfig" + } + ] + }, "ToggleableConfig_for_EnvFileConfig": { "anyOf": [ { diff --git a/mirrord/config/src/feature.rs b/mirrord/config/src/feature.rs index 0487da131a1..b17cee800e8 100644 --- a/mirrord/config/src/feature.rs +++ b/mirrord/config/src/feature.rs @@ -79,7 +79,7 @@ pub struct FeatureConfig { #[config(nested, toggleable)] pub network: NetworkConfig, - /// ## feature.copy_target {#feature-copy-target} + /// ## feature.copy_target {#feature-copy_target} /// /// Creates a new copy of the target. mirrord will use this copy instead of the original target /// (e.g. intercept network traffic). This feature requires a [mirrord operator](https://mirrord.dev/docs/teams/introduction/). diff --git a/mirrord/config/src/feature/copy_target.rs b/mirrord/config/src/feature/copy_target.rs index 3e873737d33..e1fdd60e5f9 100644 --- a/mirrord/config/src/feature/copy_target.rs +++ b/mirrord/config/src/feature/copy_target.rs @@ -7,10 +7,25 @@ use crate::{ util::MirrordToggleableConfig, }; -/// TODO json schema +/// Allows the user to target a pod created dynamically from the orignal [`target`](#target). +/// The new pod inherits most of the original target's specification, e.g. labels. +/// +/// ```json +/// { +/// "feature": { +/// "copy_target": { +/// "scale_down": true +/// } +/// } +/// } +/// ``` #[derive(Clone, Debug, Deserialize, JsonSchema, Default)] #[cfg_attr(test, derive(PartialEq, Eq))] pub struct CopyTargetFileConfig { + /// ### feature.copy_target.scale_down {#feature-copy_target-scale_down} + /// + /// If this option is set and [`target`](#target) is a deployment, + /// mirrord will scale it down by 1 for the time the copied pod is alive. pub scale_down: Option, } diff --git a/mirrord/config/src/lib.rs b/mirrord/config/src/lib.rs index cfc6f6e0e61..9d8b44c812b 100644 --- a/mirrord/config/src/lib.rs +++ b/mirrord/config/src/lib.rs @@ -143,7 +143,11 @@ const PAUSE_WITHOUT_STEAL_WARNING: &str = /// "ignore_localhost": false, /// "unix_streams": "bear.+" /// }, -/// "dns": false +/// "dns": false, +/// "copy_target": { +/// "enabled": true, +/// "scale_down": false +/// } /// }, /// }, /// "operator": true,