forked from metalbear-co/mirrord
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathmirrord-schema.json
2039 lines (2039 loc) · 96 KB
/
mirrord-schema.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
{
"$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 use a configuration file in the CLI, use the `-f <CONFIG_PATH>` flag. Or if using VSCode Extension or JetBrains plugin, simply create a `.mirrord/mirrord.json` file or use the UI.\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\", \"target\": { \"path\": \"pod/bear-pod\", \"namespace\": \"default\" }, \"connect_tcp\": null, \"agent\": { \"log_level\": \"info\", \"json_log\": false, \"labels\": { \"user\": \"meow\" }, \"annotations\": { \"cats.io/inject\": \"enabled\" }, \"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, \"metrics\": \"0.0.0.0:9000\", }, \"feature\": { \"env\": { \"include\": \"DATABASE_USER;PUBLIC_ENV\", \"exclude\": \"DATABASE_PASSWORD;SECRET_ENV\", \"override\": { \"DATABASE_CONNECTION\": \"db://localhost:7777/my-db\", \"LOCAL_BEAR\": \"panda\" }, \"mapping\": { \".+_TIMEOUT\": \"1000\" } }, \"fs\": { \"mode\": \"write\", \"read_write\": \".+\\\\.json\" , \"read_only\": [ \".+\\\\.yaml\", \".+important-file\\\\.txt\" ], \"local\": [ \".+\\\\.js\", \".+\\\\.mjs\" ] }, \"network\": { \"incoming\": { \"mode\": \"steal\", \"http_filter\": { \"header_filter\": \"host: api\\\\..+\" }, \"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\": { \"enabled\": true, \"filter\": { \"local\": [\"1.1.1.0/24:1337\", \"1.1.5.0/24\", \"google.com\"] } } }, \"copy_target\": { \"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": {
"title": "accept_invalid_certificates {#root-accept_invalid_certificates}",
"description": "Controls whether or not mirrord accepts invalid TLS certificates (e.g. self-signed certificates).\n\nIf not provided, mirrord will use value from the kubeconfig.",
"type": [
"boolean",
"null"
]
},
"agent": {
"title": "agent {#root-agent}",
"anyOf": [
{
"$ref": "#/definitions/AgentFileConfig"
},
{
"type": "null"
}
]
},
"connect_tcp": {
"title": "connect_tcp {#root-connect_tcp}",
"description": "IP:PORT to connect to instead of using k8s api, for testing purposes.\n\n```json { \"connect_tcp\": \"10.10.0.100:7777\" } ```",
"type": [
"string",
"null"
]
},
"container": {
"title": "container {#root-container}",
"anyOf": [
{
"$ref": "#/definitions/ContainerFileConfig"
},
{
"type": "null"
}
]
},
"experimental": {
"title": "experimental {#root-experimental}",
"anyOf": [
{
"$ref": "#/definitions/ExperimentalFileConfig"
},
{
"type": "null"
}
]
},
"external_proxy": {
"title": "external_proxy {#root-external_proxy}",
"anyOf": [
{
"$ref": "#/definitions/ExternalProxyFileConfig"
},
{
"type": "null"
}
]
},
"feature": {
"title": "feature {#root-feature}",
"anyOf": [
{
"$ref": "#/definitions/FeatureFileConfig"
},
{
"type": "null"
}
]
},
"internal_proxy": {
"title": "internal_proxy {#root-internal_proxy}",
"anyOf": [
{
"$ref": "#/definitions/InternalProxyFileConfig"
},
{
"type": "null"
}
]
},
"kube_context": {
"title": "kube_context {#root-kube_context}",
"description": "Kube context to use from the kubeconfig file. Will use current context if not specified.\n\n```json { \"kube_context\": \"mycluster\" } ```",
"type": [
"string",
"null"
]
},
"kubeconfig": {
"title": "kubeconfig {#root-kubeconfig}",
"description": "Path to a kubeconfig file, if not specified, will use `KUBECONFIG`, or `~/.kube/config`, or the in-cluster config.\n\n```json { \"kubeconfig\": \"~/bear/kube-config\" } ```",
"type": [
"string",
"null"
]
},
"operator": {
"title": "operator {#root-operator}",
"description": "Whether mirrord should use the operator. If not set, mirrord will first attempt to use the operator, but continue without it in case of failure.",
"type": [
"boolean",
"null"
]
},
"sip_binaries": {
"title": "sip_binaries {#root-sip_binaries}",
"description": "Binaries to patch (macOS SIP).\n\nUse this when mirrord isn't loaded to protected binaries that weren't automatically patched.\n\nRuns `endswith` on the binary path (so `bash` would apply to any binary ending with `bash` while `/usr/bin/bash` would apply only for that binary).\n\n```json { \"sip_binaries\": \"bash;python\" } ```",
"anyOf": [
{
"$ref": "#/definitions/VecOrSingle_for_String"
},
{
"type": "null"
}
]
},
"skip_build_tools": {
"title": "skip_build_tools {#root-skip_build_tools}",
"description": "Allows mirrord to skip build tools. Useful when running command lines that build and run the application in a single command.\n\nDefaults to `true`.\n\nBuild-Tools: `[\"as\", \"cc\", \"ld\", \"go\", \"air\", \"asm\", \"cc1\", \"cgo\", \"dlv\", \"gcc\", \"git\", \"link\", \"math\", \"cargo\", \"hpack\", \"rustc\", \"compile\", \"collect2\", \"cargo-watch\", \"debugserver\"]`",
"type": [
"boolean",
"null"
]
},
"skip_processes": {
"title": "skip_processes {#root-skip_processes}",
"description": "Allows mirrord to skip unwanted processes.\n\nUseful when process A spawns process B, and the user wants mirrord to operate only on process B. Accepts a single value, or multiple values separated by `;`.\n\n```json { \"skip_processes\": \"bash;node\" } ```",
"anyOf": [
{
"$ref": "#/definitions/VecOrSingle_for_String"
},
{
"type": "null"
}
]
},
"target": {
"title": "target {#root-target}",
"anyOf": [
{
"$ref": "#/definitions/TargetFileConfig"
},
{
"type": "null"
}
]
},
"telemetry": {
"title": "telemetry {#root-telemetry}",
"description": "Controls whether or not mirrord sends telemetry data to MetalBear cloud. Telemetry sent doesn't contain personal identifiers or any data that should be considered sensitive. It is used to improve the product. [For more information](https://github.com/metalbear-co/mirrord/blob/main/TELEMETRY.md)",
"type": [
"boolean",
"null"
]
},
"use_proxy": {
"title": "use_proxy {#root-use_proxy}",
"description": "When disabled, mirrord will remove `HTTP[S]_PROXY` env variables before doing any network requests. This is useful when the system sets a proxy but you don't want mirrord to use it. This also applies to the mirrord process (as it just removes the env). If the remote pod sets this env, the mirrord process will still use it.",
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false,
"definitions": {
"AdvancedFsUserConfig": {
"description": "Allows the user to specify the default behavior for file operations:\n\n1. `\"read\"` or `true` - Read from the remote file system (default) 2. `\"write\"` - Read/Write from the remote file system. 3. `\"local\"` or `false` - Read from the local file system. 4. `\"localwithoverrides\"` - perform fs operation locally, unless the path matches a pre-defined or user-specified exception.\n\n> Note: by default, some paths are read locally or remotely, regardless of the selected FS mode. > This is described in further detail below.\n\nBesides the default behavior, the user can specify behavior for specific regex patterns. Case insensitive.\n\n1. `\"read_write\"` - List of patterns that should be read/write remotely. 2. `\"read_only\"` - List of patterns that should be read only remotely. 3. `\"local\"` - List of patterns that should be read locally. 4. `\"not_found\"` - List of patters that should never be read nor written. These files should be treated as non-existent. 4. `\"mapping\"` - Map of patterns and their corresponding replacers. The replacement happens before any specific behavior as defined above or mode (uses [`Regex::replace`](https://docs.rs/regex/latest/regex/struct.Regex.html#method.replace))\n\nThe logic for choosing the behavior is as follows:\n\n1. Check agains \"mapping\" if path needs to be replaced, if matched then continue to next step with new path after replacements otherwise continue as usual. 2. Check if one of the patterns match the file path, do the corresponding action. There's no specified order if two lists match the same path, we will use the first one (and we do not guarantee what is first).\n\n**Warning**: Specifying the same path in two lists is unsupported and can lead to undefined behaviour.\n\n3. There are pre-defined exceptions to the set FS mode. 1. Paths that match [the patterns defined here](https://github.com/metalbear-co/mirrord/tree/latest/mirrord/layer/src/file/filter/read_local_by_default.rs) are read locally by default. 2. Paths that match [the patterns defined here](https://github.com/metalbear-co/mirrord/tree/latest/mirrord/layer/src/file/filter/read_remote_by_default.rs) are read remotely by default when the mode is `localwithoverrides`. 3. Paths that match [the patterns defined here](https://github.com/metalbear-co/mirrord/tree/latest/mirrord/layer/src/file/filter/not_found_by_default.rs) under the running user's home directory will not be found by the application when the mode is not `local`.\n\nIn order to override that default setting for a path, or a pattern, include it the appropriate pattern set from above. E.g. in order to read files under `/etc/` remotely even though it is covered by [the set of patterns that are read locally by default](https://github.com/metalbear-co/mirrord/tree/latest/mirrord/layer/src/file/filter/read_local_by_default.rs), add `\"^/etc/.\"` to the `read_only` set.\n\n4. If none of the above match, use the default behavior (mode).\n\nFor more information, check the file operations [technical reference](https://mirrord.dev/docs/reference/fileops/).\n\n```json { \"feature\": { \"fs\": { \"mode\": \"write\", \"read_write\": \".+\\\\.json\" , \"read_only\": [ \".+\\\\.yaml\", \".+important-file\\\\.txt\" ], \"local\": [ \".+\\\\.js\", \".+\\\\.mjs\" ], \"not_found\": [ \"\\\\.config/gcloud\" ] } } } ```",
"type": "object",
"properties": {
"local": {
"title": "feature.fs.local {#feature-fs-local}",
"description": "Specify file path patterns that if matched will be opened locally.",
"anyOf": [
{
"$ref": "#/definitions/VecOrSingle_for_String"
},
{
"type": "null"
}
]
},
"mapping": {
"title": "feature.fs.mapping {#feature-fs-mapping}",
"description": "Specify map of patterns that if matched will replace the path according to specification.\n\n*Capture groups are allowed.*\n\nExample: ```json { \"^/home/(?<user>\\\\S+)/dev/tomcat\": \"/etc/tomcat\" \"^/home/(?<user>\\\\S+)/dev/config/(?<app>\\\\S+)\": \"/mnt/configs/${user}-$app\" } ``` Will do the next replacements for any io operaton\n\n`/home/johndoe/dev/tomcat/context.xml` => `/etc/tomcat/context.xml` `/home/johndoe/dev/config/api/app.conf` => `/mnt/configs/johndoe-api/app.conf`\n\n- Relative paths: this feature (currently) does not apply mappings to relative paths, e.g. `../dev`.",
"type": [
"object",
"null"
],
"additionalProperties": {
"type": "string"
}
},
"mode": {
"title": "feature.fs.mode {#feature-fs-mode}",
"anyOf": [
{
"$ref": "#/definitions/FsModeConfig"
},
{
"type": "null"
}
]
},
"not_found": {
"title": "feature.fs.not_found {#feature-fs-not_found}",
"description": "Specify file path patterns that if matched will be treated as non-existent.",
"anyOf": [
{
"$ref": "#/definitions/VecOrSingle_for_String"
},
{
"type": "null"
}
]
},
"read_only": {
"title": "feature.fs.read_only {#feature-fs-read_only}",
"description": "Specify file path patterns that if matched will be read from the remote. if file matching the pattern is opened for writing or read/write it will be opened locally.",
"anyOf": [
{
"$ref": "#/definitions/VecOrSingle_for_String"
},
{
"type": "null"
}
]
},
"read_write": {
"title": "feature.fs.read_write {#feature-fs-read_write}",
"description": "Specify file path patterns that if matched will be read and written to the remote.",
"anyOf": [
{
"$ref": "#/definitions/VecOrSingle_for_String"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"AgentFileConfig": {
"description": "Configuration for the mirrord-agent pod that is spawned in the Kubernetes cluster.\n\nWe provide sane defaults for this option, so you don't have to set up anything here.\n\n```json { \"agent\": { \"log_level\": \"info\", \"json_log\": false, \"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\": false } } ```",
"type": "object",
"properties": {
"annotations": {
"title": "agent.annotations {#agent-annotations}",
"description": "Allows setting up custom annotations for the agent Job and Pod.\n\n```json { \"annotations\": { \"cats.io/inject\": \"enabled\" \"prometheus.io/scrape\": \"true\", \"prometheus.io/port\": \"9000\" } } ```",
"type": [
"object",
"null"
],
"additionalProperties": {
"type": "string"
}
},
"check_out_of_pods": {
"title": "agent.check_out_of_pods {#agent-check_out_of_pods}",
"description": "Determine if to check whether there is room for agent job in target node. (Not applicable when using ephemeral containers feature)\n\nCan be disabled if the check takes too long and you are sure there is enough resources on each node",
"type": [
"boolean",
"null"
]
},
"communication_timeout": {
"title": "agent.communication_timeout {#agent-communication_timeout}",
"description": "Controls how long the agent lives when there are no connections.\n\nEach connection has its own heartbeat mechanism, so even if the local application has no messages, the agent stays alive until there are no more heartbeat messages.",
"type": [
"integer",
"null"
],
"format": "uint16",
"minimum": 0.0
},
"disabled_capabilities": {
"title": "agent.disabled_capabilities {#agent-disabled_capabilities}",
"description": "Disables specified Linux capabilities for the agent container. If nothing is disabled here, agent uses `NET_ADMIN`, `NET_RAW`, `SYS_PTRACE` and `SYS_ADMIN`.\n\nHas no effect when using the targetless mode, as targetless agent containers have no capabilities.",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/definitions/LinuxCapability"
}
},
"dns": {
"title": "agent.dns {#agent-dns}",
"anyOf": [
{
"$ref": "#/definitions/FileAgentDnsConfig"
},
{
"type": "null"
}
]
},
"ephemeral": {
"title": "agent.ephemeral {#agent-ephemeral}",
"description": "Runs the agent as an [ephemeral container](https://kubernetes.io/docs/concepts/workloads/pods/ephemeral-containers/)\n\nDefaults to `false`.",
"type": [
"boolean",
"null"
]
},
"flush_connections": {
"title": "agent.flush_connections {#agent-flush_connections}",
"description": "Flushes existing connections when starting to steal, might fix issues where connections aren't stolen (due to being already established)\n\nDefaults to `true`.",
"type": [
"boolean",
"null"
]
},
"image": {
"title": "agent.image {#agent-image}",
"description": "Name of the agent's docker image.\n\nUseful when a custom build of mirrord-agent is required, or when using an internal registry.\n\nDefaults to the latest stable image `\"ghcr.io/metalbear-co/mirrord:latest\"`.\n\n```json { \"image\": \"internal.repo/images/mirrord:latest\" } ```\n\nComplete setup:\n\n```json { \"image\": { \"registry\": \"internal.repo/images/mirrord\", \"tag\": \"latest\" } } ```",
"anyOf": [
{
"$ref": "#/definitions/AgentImageFileConfig"
},
{
"type": "null"
}
]
},
"image_pull_policy": {
"title": "agent.image_pull_policy {#agent-image_pull_policy}",
"description": "Controls when a new agent image is downloaded.\n\nSupports `\"IfNotPresent\"`, `\"Always\"`, `\"Never\"`, or any valid kubernetes [image pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy)\n\nDefaults to `\"IfNotPresent\"`",
"type": [
"string",
"null"
]
},
"image_pull_secrets": {
"title": "agent.image_pull_secrets {#agent-image_pull_secrets}",
"description": "List of secrets the agent pod has access to.\n\nTakes an array of entries with the format `{ name: <secret-name> }`.\n\nRead more [here](https://kubernetes.io/docs/concepts/containers/images/#referring-to-an-imagepullsecrets-on-a-pod).\n\n```json { \"agent\": { \"image_pull_secrets\": [ { \"name\": \"secret-key-1\" }, { \"name\": \"secret-key-2\" } ] } } ```",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/definitions/AgentPullSecret"
}
},
"json_log": {
"title": "agent.json_log {#agent-json_log}",
"description": "Controls whether the agent produces logs in a human-friendly format, or json.\n\n```json { \"agent\": { \"json_log\": true } } ```",
"type": [
"boolean",
"null"
]
},
"labels": {
"title": "agent.labels {#agent-labels}",
"description": "Allows setting up custom labels for the agent Job and Pod.\n\n```json { \"labels\": { \"user\": \"meow\", \"state\": \"asleep\" } } ```",
"type": [
"object",
"null"
],
"additionalProperties": {
"type": "string"
}
},
"log_level": {
"title": "agent.log_level {#agent-log_level}",
"description": "Log level for the agent.\n\nSupports `\"trace\"`, `\"debug\"`, `\"info\"`, `\"warn\"`, `\"error\"`, or any string that would work with `RUST_LOG`.\n\n```json { \"agent\": { \"log_level\": \"mirrord=debug,warn\" } } ```",
"type": [
"string",
"null"
]
},
"metrics": {
"title": "agent.metrics {#agent-metrics}",
"description": "Enables prometheus metrics for the agent pod.\n\nYou might need to add annotations to the agent pod depending on how prometheus is configured to scrape for metrics.\n\n```json { \"metrics\": \"0.0.0.0:9000\" } ```",
"type": [
"string",
"null"
]
},
"namespace": {
"title": "agent.namespace {#agent-namespace}",
"description": "Namespace where the agent shall live. Note: Doesn't work with ephemeral containers. Defaults to the current kubernetes namespace.",
"type": [
"string",
"null"
]
},
"network_interface": {
"title": "agent.network_interface {#agent-network_interface}",
"description": "Which network interface to use for mirroring.\n\nThe default behavior is try to access the internet and use that interface. If that fails it uses `eth0`.",
"type": [
"string",
"null"
]
},
"nftables": {
"title": "agent.nftables {#agent-nftables}",
"description": "Use iptables-nft instead of iptables-legacy. Defaults to `false`.\n\nNeeded if your mesh uses nftables instead of iptables-legacy,",
"type": [
"boolean",
"null"
]
},
"node_selector": {
"title": "agent.node_selector {#agent-node_selector}",
"description": "Allows setting up custom node selector for the agent Pod. Applies only to targetless runs, as targeted agent always runs on the same node as its target container.\n\n```json { \"node_selector\": { \"kubernetes.io/hostname\": \"node1\" } } ```",
"type": [
"object",
"null"
],
"additionalProperties": {
"type": "string"
}
},
"privileged": {
"title": "agent.privileged {#agent-privileged}",
"description": "Run the mirror agent as privileged container. Defaults to `false`.\n\nMight be needed in strict environments such as Bottlerocket.\n\nHas no effect when using the targetless mode, as targetless agent containers are never privileged.",
"type": [
"boolean",
"null"
]
},
"resources": {
"title": "agent.resources {#agent-resources}",
"description": "Set pod resource reqirements. (not with ephemeral agents) Default is ```json { \"requests\": { \"cpu\": \"1m\", \"memory\": \"1Mi\" }, \"limits\": { \"cpu\": \"100m\", \"memory\": \"100Mi\" } } ```",
"anyOf": [
{
"$ref": "#/definitions/io.k8s.api.core.v1.ResourceRequirements"
},
{
"type": "null"
}
]
},
"service_account": {
"title": "agent.service_account {#agent-service_account}",
"description": "Allows setting up custom Service Account for the agent Job and Pod.\n\n```json { \"service_account\": \"my-service-account\" } ```",
"type": [
"string",
"null"
]
},
"startup_timeout": {
"title": "agent.startup_timeout {#agent-startup_timeout}",
"description": "Controls how long to wait for the agent to finish initialization.\n\nIf initialization takes longer than this value, mirrord exits.\n\nDefaults to `60`.",
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0.0
},
"tolerations": {
"title": "agent.tolerations {#agent-tolerations}",
"description": "Set pod tolerations. (not with ephemeral agents).\n\nDefaults to `operator: Exists`.\n\n```json [ { \"key\": \"meow\", \"operator\": \"Exists\", \"effect\": \"NoSchedule\" } ] ```\n\nSet to an empty array to have no tolerations at all",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/definitions/io.k8s.api.core.v1.Toleration"
}
},
"ttl": {
"title": "agent.ttl {#agent-ttl}",
"description": "Controls how long the agent pod persists for after the agent exits (in seconds).\n\nCan be useful for collecting logs.\n\nDefaults to `1`.",
"type": [
"integer",
"null"
],
"format": "uint16",
"minimum": 0.0
}
},
"additionalProperties": false
},
"AgentImageFileConfig": {
"description": "<!--${internal}--> Allows us to support the dual configuration for the agent image.\n\nWhatever values missing are replaced with our defaults.",
"anyOf": [
{
"description": "The shortened version of: `image: \"repo/mirrord:latest\"`.",
"type": [
"string",
"null"
]
},
{
"description": "Expanded version: `image: { registry: \"repo/mirrord\", tag: \"latest\" }`.",
"type": "object",
"properties": {
"registry": {
"type": [
"string",
"null"
]
},
"tag": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
]
},
"AgentPullSecret": {
"description": "<!--${internal}--> Specifies a secret reference for the agent pod.",
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"description": "Name of the secret.",
"type": "string"
}
}
},
"ConcurrentSteal": {
"description": "(Operator Only): Allows overriding port locks\n\nCan be set to either `\"continue\"` or `\"override\"`.\n\n- `\"continue\"`: Continue with normal execution - `\"override\"`: If port lock detected then override it with new lock and force close the original locking connection.",
"oneOf": [
{
"description": "<!--${internal}--> ### override\n\nOverride any port lock and force close the original lock connection",
"type": "string",
"enum": [
"override"
]
},
{
"description": "<!--${internal}--> ### continue\n\nContinue with normal execution",
"type": "string",
"enum": [
"continue"
]
},
{
"description": "<!--${internal}--> ### abort\n\nAbort Execution when trying to steal traffic from a target whose traffic is already being stolen.",
"type": "string",
"enum": [
"abort"
]
}
]
},
"ContainerFileConfig": {
"description": "Unstable: `mirrord container` command specific config.",
"type": "object",
"properties": {
"cli_extra_args": {
"title": "container.cli_extra_args {#container-cli_extra_args}",
"description": "Any extra args to use when creating the sidecar mirrord-cli container.\n\nThis is useful when you want to use portforwarding, passing `-p local:container` won't work for main command but adding them here will work ```json { \"container\": { \"cli_extra_args\": [\"-p\", \"local:container\"] } } ```",
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"cli_image": {
"title": "container.cli_image {#container-cli_image}",
"description": "Tag of the `mirrord-cli` image you want to use.\n\nDefaults to `\"ghcr.io/metalbear-co/mirrord-cli:<cli version>\"`.",
"type": [
"string",
"null"
]
},
"cli_image_lib_path": {
"title": "container.cli_image_lib_path {#container-cli_image}",
"description": "Path of the mirrord-layer lib inside the specified mirrord-cli image.\n\nDefaults to `\"/opt/mirrord/lib/libmirrord_layer.so\"`.",
"type": [
"string",
"null"
]
},
"cli_prevent_cleanup": {
"title": "container.cli_prevent_cleanup {#container-cli_extra_args}",
"description": "Don't add `--rm` to sidecar command to prevent cleanup.",
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"CopyTargetFileConfig": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "object",
"properties": {
"enabled": {
"type": [
"boolean",
"null"
]
},
"scale_down": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
}
]
},
"CronJobTarget": {
"type": "object",
"required": [
"cron_job"
],
"properties": {
"container": {
"type": [
"string",
"null"
]
},
"cron_job": {
"type": "string"
}
},
"additionalProperties": false
},
"DeploymentTarget": {
"description": "<!--${internal}--> Mirror the deployment specified by [`DeploymentTarget::deployment`].",
"type": "object",
"required": [
"deployment"
],
"properties": {
"container": {
"type": [
"string",
"null"
]
},
"deployment": {
"description": "<!--${internal}--> Deployment to mirror.",
"type": "string"
}
},
"additionalProperties": false
},
"DnsFileConfig": {
"description": "Resolve DNS via the remote pod.\n\nDefaults to `true`.\n\nMind that: - DNS resolving can be done in multiple ways. Some frameworks use `getaddrinfo`/`gethostbyname` functions, while others communicate directly with the DNS server at port `53` and perform a sort of manual resolution. Just enabling the `dns` feature in mirrord might not be enough. If you see an address resolution error, try enabling the [`fs`](#feature-fs) feature, and setting `read_only: [\"/etc/resolv.conf\"]`. - DNS filter currently works only with frameworks that use `getaddrinfo`/`gethostbyname` functions.",
"type": "object",
"properties": {
"enabled": {
"type": [
"boolean",
"null"
]
},
"filter": {
"title": "feature.network.dns.filter {#feature-network-dns-filter}",
"description": "Unstable: the precise syntax of this config is subject to change.",
"anyOf": [
{
"$ref": "#/definitions/DnsFilterConfig"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"DnsFilterConfig": {
"description": "List of addresses/ports/subnets that should be resolved through either the remote pod or local app, depending how you set this up with either `remote` or `local`.\n\nYou may use this option to specify when DNS resolution is done from the remote pod (which is the default behavior when you enable remote DNS), or from the local app (default when you have remote DNS disabled).\n\nTakes a list of values, such as:\n\n- Only queries for hostname `my-service-in-cluster` will go through the remote pod.\n\n```json { \"remote\": [\"my-service-in-cluster\"] } ```\n\n- Only queries for addresses in subnet `1.1.1.0/24` with service port `1337`` will go through the remote pod.\n\n```json { \"remote\": [\"1.1.1.0/24:1337\"] } ```\n\n- Only queries for hostname `google.com` with service port `1337` or `7331` will go through the remote pod.\n\n```json { \"remote\": [\"google.com:1337\", \"google.com:7331\"] } ```\n\n- Only queries for `localhost` with service port `1337` will go through the local app.\n\n```json { \"local\": [\"localhost:1337\"] } ```\n\n- Only queries with service port `1337` or `7331` will go through the local app.\n\n```json { \"local\": [\":1337\", \":7331\"] } ```\n\nValid values follow this pattern: `[name|address|subnet/mask][:port]`.",
"oneOf": [
{
"description": "DNS queries matching what is specified here will go through the remote pod, everything else will go through local.",
"type": "object",
"required": [
"remote"
],
"properties": {
"remote": {
"$ref": "#/definitions/VecOrSingle_for_String"
}
},
"additionalProperties": false
},
{
"description": "DNS queries matching what is specified here will go through the local app, everything else will go through the remote pod.",
"type": "object",
"required": [
"local"
],
"properties": {
"local": {
"$ref": "#/definitions/VecOrSingle_for_String"
}
},
"additionalProperties": false
}
]
},
"EnvFileConfig": {
"description": "Allows the user to set or override the local process' environment variables with the ones from the remote pod.\n\nCan be set to one of the options:\n\n1. `false` - Disables the feature, won't have remote environment variables. 2. `true` - Enables the feature, will obtain remote environment variables. 3. object - see below (means `true` + additional configuration).\n\nWhich environment variables to load from the remote pod are controlled by setting either [`include`](#feature-env-include) or [`exclude`](#feature-env-exclude).\n\nSee the environment variables [reference](https://mirrord.dev/docs/reference/env/) for more details.\n\n```json { \"feature\": { \"env\": { \"include\": \"DATABASE_USER;PUBLIC_ENV;MY_APP_*\", \"exclude\": \"DATABASE_PASSWORD;SECRET_ENV\", \"override\": { \"DATABASE_CONNECTION\": \"db://localhost:7777/my-db\", \"LOCAL_BEAR\": \"panda\" }, \"mapping\": { \".+_TIMEOUT\": \"1000\" } } } } ```",
"type": "object",
"properties": {
"env_file": {
"title": "feature.env_file {#feature-env-file}",
"description": "Allows for passing environment variables from an env file.\n\nThese variables will override environment fetched from the remote target.",
"type": [
"string",
"null"
]
},
"exclude": {
"title": "feature.env.exclude {#feature-env-exclude}",
"description": "Include the remote environment variables in the local process that are **NOT** specified by this option. Variable names can be matched using `*` and `?` where `?` matches exactly one occurrence of any character and `*` matches arbitrary many (including zero) occurrences of any character.\n\nSome of the variables that are excluded by default: `PATH`, `HOME`, `HOMEPATH`, `CLASSPATH`, `JAVA_EXE`, `JAVA_HOME`, `PYTHONPATH`.\n\nCan be passed as a list or as a semicolon-delimited string (e.g. `\"VAR;OTHER_VAR\"`).",
"anyOf": [
{
"$ref": "#/definitions/VecOrSingle_for_String"
},
{
"type": "null"
}
]
},
"include": {
"title": "feature.env.include {#feature-env-include}",
"description": "Include only these remote environment variables in the local process. Variable names can be matched using `*` and `?` where `?` matches exactly one occurrence of any character and `*` matches arbitrary many (including zero) occurrences of any character.\n\nCan be passed as a list or as a semicolon-delimited string (e.g. `\"VAR;OTHER_VAR\"`).\n\nSome environment variables are excluded by default (`PATH` for example), including these requires specifying them with `include`",
"anyOf": [
{
"$ref": "#/definitions/VecOrSingle_for_String"
},
{
"type": "null"
}
]
},
"load_from_process": {
"title": "feature.env.load_from_process {#feature-env-load_from_process}",
"description": "Allows for changing the way mirrord loads remote environment variables. If set, the variables are fetched after the user application is started.\n\nThis setting is meant to resolve issues when using mirrord via the IntelliJ plugin on WSL and the remote environment contains a lot of variables.",
"type": [
"boolean",
"null"
]
},
"mapping": {
"title": "feature.env.mapping {#feature-env-mapping}",
"description": "Specify map of patterns that if matched will replace the value according to specification.\n\n*Capture groups are allowed.*\n\nExample: ```json { \".+_TIMEOUT\": \"10000\" \"LOG_.+_VERBOSITY\": \"debug\" \"(\\w+)_(\\d+)\": \"magic-value\" } ```\n\nWill do the next replacements for environment variables that match:\n\n* `CONNECTION_TIMEOUT: 500` => `CONNECTION_TIMEOUT: 10000`\n\n* `LOG_FILE_VERBOSITY: info` => `LOG_FILE_VERBOSITY: debug`\n\n* `DATA_1234: common-value` => `DATA_1234: magic-value`",
"type": [
"object",
"null"
],
"additionalProperties": {
"type": "string"
}
},
"override": {
"title": "feature.env.override {#feature-env-override}",
"description": "Allows setting or overriding environment variables (locally) with a custom value.\n\nFor example, if the remote pod has an environment variable `REGION=1`, but this is an undesirable value, it's possible to use `override` to set `REGION=2` (locally) instead.\n\nEnvironment specified here will also override variables passed via the env file.",
"type": [
"object",
"null"
],
"additionalProperties": {
"type": "string"
}
},
"unset": {
"title": "feature.env.unset {#feature-env-unset}",
"description": "Allows unsetting environment variables in the executed process.\n\nThis is useful for when some system/user-defined environment like `AWS_PROFILE` make the application behave as if it's running locally, instead of using the remote settings. The unsetting happens from extension (if possible)/CLI and when process initializes. In some cases, such as Go the env might not be able to be modified from the process itself. This is case insensitive, meaning if you'd put `AWS_PROFILE` it'd unset both `AWS_PROFILE` and `Aws_Profile` and other variations.",
"anyOf": [
{
"$ref": "#/definitions/VecOrSingle_for_String"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"ExperimentalFileConfig": {
"description": "mirrord Experimental features. This shouldn't be used unless someone from MetalBear/mirrord tells you to.",
"type": "object",
"properties": {
"disable_reuseaddr": {
"title": "_experimental_ disable_reuseaddr {#experimental-disable_reuseaddr}",
"description": "Disables the `SO_REUSEADDR` socket option on sockets that mirrord steals/mirrors. On macOS the application can use the same address many times but then we don't steal it correctly. This probably should be on by default but we want to gradually roll it out. <https://github.com/metalbear-co/mirrord/issues/2819> This option applies only on macOS.",
"type": [
"boolean",
"null"
]
},
"enable_exec_hooks_linux": {
"title": "_experimental_ enable_exec_hooks_linux {#experimental-enable_exec_hooks_linux}",
"description": "Enables exec hooks on Linux. Enable Linux hooks can fix issues when the application shares sockets with child commands (e.g Python web servers with reload), but the feature is not stable and may cause other issues.",
"type": [
"boolean",
"null"
]
},
"hide_ipv6_interfaces": {
"title": "_experimental_ hide_ipv6_interfaces {#experimental-hide_ipv6_interfaces}",
"description": "Enables `getifaddrs` hook that removes IPv6 interfaces from the list returned by libc.",
"type": [
"boolean",
"null"
]
},
"readlink": {
"title": "_experimental_ readlink {#experimental-readlink}",
"description": "DEPRECATED, WILL BE REMOVED",
"type": [
"boolean",
"null"
]
},
"readonly_file_buffer": {
"title": "_experimental_ readonly_file_buffer {#experimental-readonly_file_buffer}",
"description": "Sets buffer size for readonly remote files (in bytes, for example 4096). If set, such files will be read in chunks and buffered locally. This improves performace when the user application reads data in small portions.\n\nSetting to 0 disables file buffering.\n\n<https://github.com/metalbear-co/mirrord/issues/2069>",
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0.0
},
"tcp_ping4_mock": {
"title": "_experimental_ tcp_ping4_mock {#experimental-tcp_ping4_mock}",
"description": "<https://github.com/metalbear-co/mirrord/issues/2421#issuecomment-2093200904>",
"type": [
"boolean",
"null"
]
},
"trust_any_certificate": {
"title": "_experimental_ trust_any_certificate {#experimental-trust_any_certificate}",
"description": "Enables trusting any certificate on macOS, useful for <https://github.com/golang/go/issues/51991#issuecomment-2059588252>",
"type": [
"boolean",
"null"
]
},
"use_dev_null": {
"title": "_experimental_ use_dev_null {#experimental-use_dev_null}",
"description": "Uses /dev/null for creating local fake files (should be better than using /tmp)",
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"ExternalProxyFileConfig": {
"description": "Configuration for the external proxy mirrord spawns when using the `mirrord container` command. This proxy is used to allow the internal proxy running in sidecar to connect to the mirrord agent.\n\nIf you get `ConnectionRefused` errors, increasing the timeouts a bit might solve the issue.\n\n```json { \"external_proxy\": { \"start_idle_timeout\": 30, \"idle_timeout\": 5 } } ```",
"type": "object",
"properties": {
"idle_timeout": {
"title": "external_proxy.idle_timeout {#external_proxy-idle_timeout}",
"description": "How much time to wait while we don't have any active connections before exiting.\n\nCommon cases would be running a chain of processes that skip using the layer and don't connect to the proxy.\n\n```json { \"external_proxy\": { \"idle_timeout\": 30 } } ```",
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0.0
},
"log_destination": {
"title": "external_proxy.log_destination {#external_proxy-log_destination}",
"description": "Set the log file destination for the external proxy.",
"type": [
"string",
"null"
]
},
"log_level": {
"title": "external_proxy.log_level {#external_proxy-log_level}",
"description": "Sets the log level for the external proxy.\n\nFollows the `RUST_LOG` convention (i.e `mirrord=trace`), and will only be used if `external_proxy.log_destination` is set",
"type": [
"string",
"null"
]
},
"start_idle_timeout": {
"title": "external_proxy.start_idle_timeout {#external_proxy-start_idle_timeout}",
"description": "How much time to wait for the first connection to the external proxy in seconds.\n\nCommon cases would be running with dlv or any other debugger, which sets a breakpoint on process execution, delaying the layer startup and connection to the external proxy.\n\n```json { \"external_proxy\": { \"start_idle_timeout\": 60 } } ```",
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0.0
},
"tls_certificate": {
"description": "<!--${internal}-->\n\nCertificate path to be used for wrapping external proxy tcp listener with a tcp acceptor (self-signed one will be generated automaticaly if not specified)",
"type": [
"string",
"null"
]
},
"tls_enable": {
"description": "<!--${internal}-->\n\nWhether to use TLS or a plain TCP connection.",
"type": [
"boolean",
"null"
]
},
"tls_key": {
"description": "<!--${internal}-->\n\nPrivate Key path to be used for wrapping external proxy tcp listener with a tcp acceptor (self-signed one will be generated automaticaly if not specified)",
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"FeatureFileConfig": {
"description": "Controls mirrord features.\n\nSee the [technical reference, Technical Reference](https://mirrord.dev/docs/reference/) to learn more about what each feature does.\n\nThe [`env`](#feature-env), [`fs`](#feature-fs) and [`network`](#feature-network) options have support for a shortened version, that you can see [here](#root-shortened).\n\n```json { \"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_filter\": { \"header_filter\": \"host: api\\\\..+\" }, \"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\": false, \"hostname\": true } } ```",
"type": "object",
"properties": {
"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/overview/teams/?utm_source=copytarget).\n\nThis feature is not compatible with rollout targets and running without a target (`targetless` mode).",
"anyOf": [
{
"$ref": "#/definitions/CopyTargetFileConfig"
},
{
"type": "null"
}
]
},
"env": {
"title": "feature.env {#feature-env}",
"anyOf": [
{
"$ref": "#/definitions/ToggleableConfig_for_EnvFileConfig"
},
{
"type": "null"
}
]
},
"fs": {
"title": "feature.fs {#feature-fs}",
"anyOf": [
{
"$ref": "#/definitions/ToggleableConfig_for_FsUserConfig"
},
{
"type": "null"
}
]
},
"hostname": {
"title": "feature.hostname {#feature-hostname}",
"description": "Should mirrord return the hostname of the target pod when calling `gethostname`",
"type": [
"boolean",
"null"
]
},
"network": {
"title": "feature.network {#feature-network}",
"anyOf": [
{
"$ref": "#/definitions/ToggleableConfig_for_NetworkFileConfig"
},
{
"type": "null"
}
]
},
"split_queues": {
"title": "feature.split_queues {#feature-split_queues}",
"description": "Define filters to split queues by, and make your local application consume only messages that match those filters. If you don't specify any filter for a queue that is however declared in the `MirrordWorkloadQueueRegistry` of the target you're using, a match-nothing filter will be used, and your local application will not receive any messages from that queue.",
"anyOf": [
{
"$ref": "#/definitions/SplitQueuesConfig"
},
{
"type": "null"