forked from metalbear-co/mirrord
-
Notifications
You must be signed in to change notification settings - Fork 0
/
mirrord-schema.json
1206 lines (1206 loc) · 58.7 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 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_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\": { \"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\nDefaults to `false`.",
"type": [
"boolean",
"null"
]
},
"agent": {
"title": "agent {#root-agent}",
"anyOf": [
{
"$ref": "#/definitions/AgentFileConfig"
},
{
"type": "null"
}
]
},
"connect_tcp": {
"title": "connect_tcp {#root-connect_tpc}",
"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"
]
},
"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"
]
},
"pause": {
"title": "pause {#root-pause}",
"description": "Controls target pause feature. Unstable.\n\nWith this feature enabled, the remote container is paused while this layer is connected to the agent.\n\nNote: It requires agent configuration to be set to privileged when running with the ephemeral agent option. Defaults to `false`. Note2: Pause + ephemeral might not work on Docker runtimes.",
"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\"` - Read from the remote file system (default) 2. `\"write\"` - Read/Write from the remote file system. 3. `\"local\"` - 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.\n\nThe logic for choosing the behavior is as follows:\n\n1. 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\n2. 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\n3. 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"
}
]
},
"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\", \"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\", \"pause\": false, \"flush_connections\": false, } } ```",
"type": "object",
"properties": {
"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`.",
"type": [
"array",
"null"
],
"items": {
"$ref": "#/definitions/LinuxCapability"
}
},
"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 { \"agent\": { \"image\": \"internal.repo/images/mirrord:latest\" } } ```",
"type": [
"string",
"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 hash with the format `{ name: <secret-name> }`.\n\nRead more [here](https://kubernetes.io/docs/concepts/containers/images/).\n\n```json { \"agent\": { \"image_pull_secrets\": [ { \"very-secret\": \"secret-key\" }, { \"very-secret\": \"keep-your-secrets\" } ] } } ```",
"type": [
"array",
"null"
],
"items": {
"type": "object",
"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"
]
},
"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"
]
},
"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.",
"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"
}
]
},
"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) Default is ```json [ { \"operator\": \"Exists\" } ] ```\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
},
"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"
]
}
]
},
"CopyTargetFileConfig": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "object",
"properties": {
"scale_down": {
"type": [
"boolean",
"null"
]
}
},
"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
},
"EnvFileConfig": {
"description": "Allows the user to set or override the local process' environment variables with the ones from the remote pod.\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\" } } } } ```",
"type": "object",
"properties": {
"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"
}
]
},
"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.",
"type": [
"object",
"null"
],
"additionalProperties": {
"type": "string"
}
}
},
"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 } } ```",
"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/).\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"
}
]
},
"network": {
"title": "feature.network {#feature-network}",
"anyOf": [
{
"$ref": "#/definitions/ToggleableConfig_for_NetworkFileConfig"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"FsModeConfig": {
"description": "Configuration for enabling read-only or read-write file operations.\n\nThese options are overriden by user specified overrides and mirrord default overrides.\n\nIf you set [`\"localwithoverrides\"`](#feature-fs-mode-localwithoverrides) then some files can be read/write remotely based on our default/user specified. Default option for general file configuration.\n\nThe accepted values are: `\"local\"`, `\"localwithoverrides`, `\"read\"`, or `\"write`.",
"oneOf": [
{
"title": "feature.fs.mode.local {#feature-fs-mode-local}",
"description": "mirrord won't do anything fs-related, all operations will be local.",
"type": "string",
"enum": [
"local"
]
},
{
"title": "feature.fs.mode.localwithoverrides {#feature-fs-mode-localwithoverrides}",
"description": "mirrord will run overrides on some file operations, but most will be local.",
"type": "string",
"enum": [
"localwithoverrides"
]
},
{
"title": "feature.fs.mode.read {#feature-fs-mode-read}",
"description": "mirrord will read files from the remote, but won't write to them.",
"type": "string",
"enum": [
"read"
]
},
{
"title": "feature.fs.mode.write {#feature-fs-mode-write}",
"description": "mirrord will read/write from the remote.",
"type": "string",
"enum": [
"write"
]
}
]
},
"FsUserConfig": {
"title": "feature.fs {#fs}",
"description": "Changes file operations behavior based on user configuration.\n\nSee the file operations [reference](https://mirrord.dev/docs/reference/fileops/) for more details, and [fs advanced](#fs-advanced) for more information on how to fully setup mirrord file operations.\n\n### Minimal `fs` config {#fs-minimal}\n\n```json { \"feature\": { \"fs\": \"read\" } } ```\n\n### Advanced `fs` config {#fs-advanced}\n\n```json { \"feature\": { \"fs\": { \"mode\": \"write\", \"read_write\": \".+\\.json\" , \"read_only\": [ \".+\\.yaml\", \".+important-file\\.txt\" ], \"local\": [ \".+\\.js\", \".+\\.mjs\" ] } } } ```",
"anyOf": [
{
"description": "<!--${internal}--> Basic configuration that controls the env vars `MIRRORD_FILE_OPS` and `MIRRORD_FILE_RO_OPS` (default).",
"allOf": [
{
"$ref": "#/definitions/FsModeConfig"
}
]
},
{
"description": "<!--${internal}--> Allows the user to specify both [`FsModeConfig`] (as above), and configuration for the overrides.",
"allOf": [
{
"$ref": "#/definitions/AdvancedFsUserConfig"
}
]
}
]
},
"HttpFilterFileConfig": {
"description": "Filter configuration for the HTTP traffic stealer feature.\n\nAllows the user to set a filter (regex) for the HTTP headers, so that the stealer traffic feature only captures HTTP requests that match the specified filter, forwarding unmatched requests to their original destinations.\n\nOnly does something when [`feature.network.incoming.mode`](#feature-network-incoming-mode) is set as `\"steal\"`, ignored otherwise.\n\nfor example, to filter based on header: ```json { \"header_filter\": \"host: api\\..+\", } ```\n\nfor example, to filter based on path ```json { \"path_filter\": \"host: api\\..+\", } ```",
"type": "object",
"properties": {
"header_filter": {
"title": "feature.network.incoming.http_filter.header_filter {#feature-network-incoming-http-header-filter}",
"description": "Supports regexes validated by the [`fancy-regex`](https://docs.rs/fancy-regex/latest/fancy_regex/) crate.\n\nThe HTTP traffic feature converts the HTTP headers to `HeaderKey: HeaderValue`, case-insensitive.",
"type": [
"string",
"null"
]
},
"path_filter": {
"title": "feature.network.incoming.http_filter.path_filter {#feature-network-incoming-http-path-filter}",
"description": "Supports regexes validated by the [`fancy-regex`](https://docs.rs/fancy-regex/latest/fancy_regex/) crate.\n\nCase insensitive.",
"type": [
"string",
"null"
]
},
"ports": {
"title": "feature.network.incoming.http_filter.ports {#feature-network-incoming-http_filter-ports}",
"description": "Activate the HTTP traffic filter only for these ports.\n\nOther ports will still be stolen (when `\"steal`\" is being used), they're just not checked for HTTP filtering.",
"anyOf": [
{
"$ref": "#/definitions/PortList"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"IncomingAdvancedFileConfig": {
"title": "incoming (advanced setup)",
"description": "Advanced user configuration for network incoming traffic.",
"type": "object",
"properties": {
"http_filter": {
"title": "HTTP Filter",
"description": "Sets up the HTTP traffic filter (currently, only useful when `incoming: steal`).\n\nSee [`filter`](##filter) for details.",
"anyOf": [
{
"$ref": "#/definitions/ToggleableConfig_for_HttpFilterFileConfig"
},
{
"type": "null"
}
]
},
"ignore_localhost": {
"title": "ignore_localhost",
"description": "Consider removing when adding https://github.com/metalbear-co/mirrord/issues/702",
"type": [
"boolean",
"null"
]
},
"ignore_ports": {
"title": "ignore_ports",
"description": "Ports to ignore when mirroring/stealing traffic. Useful if you want specific ports to be used locally only.",
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "uint16",
"minimum": 0.0
}
},
"listen_ports": {
"title": "listen_ports",
"description": "Mapping for local ports to actually used local ports. When application listens on a port while steal/mirror is active we fallback to random ports to avoid port conflicts. Using this configuration will always use the specified port. If this configuration doesn't exist, mirrord will try to listen on the original port and if it fails it will assign a random port\n\nThis is useful when you want to access ports exposed by your service locally For example, if you have a service that listens on port `80` and you want to access it, you probably can't listen on `80` without sudo, so you can use `[[80, 4480]]` then access it on `4480` while getting traffic from remote `80`. The value of `port_mapping` doesn't affect this.",
"type": [
"array",
"null"
],
"items": {
"type": "array",
"items": [
{
"type": "integer",
"format": "uint16",
"minimum": 0.0
},
{
"type": "integer",
"format": "uint16",
"minimum": 0.0
}
],
"maxItems": 2,
"minItems": 2
}
},
"mode": {
"title": "mode",
"description": "Allows selecting between mirrorring or stealing traffic.\n\nSee [`mode`](##mode (incoming)) for details.",
"anyOf": [
{
"$ref": "#/definitions/IncomingMode"
},
{
"type": "null"
}
]
},
"on_concurrent_steal": {
"title": "on_concurrent_steal",
"description": "(Operator Only): if value of override will force close any other connections on requested target",
"anyOf": [
{
"$ref": "#/definitions/ConcurrentSteal"
},
{
"type": "null"
}
]
},
"port_mapping": {
"title": "port_mapping",
"description": "Mapping for local ports to remote ports.\n\nThis is useful when you want to mirror/steal a port to a different port on the remote machine. For example, your local process listens on port `9333` and the container listens on port `80`. You'd use `[[9333, 80]]`",
"type": [
"array",
"null"
],
"items": {
"type": "array",
"items": [
{
"type": "integer",
"format": "uint16",
"minimum": 0.0
},
{
"type": "integer",
"format": "uint16",
"minimum": 0.0
}
],
"maxItems": 2,
"minItems": 2
}
}
},
"additionalProperties": false
},
"IncomingFileConfig": {
"title": "incoming (network)",
"description": "Controls the incoming TCP traffic feature.\n\nSee the incoming [reference](https://mirrord.dev/docs/reference/traffic/#incoming) for more details.\n\nIncoming traffic supports 2 modes of operation:\n\n1. Mirror (**default**): Sniffs the TCP data from a port, and forwards a copy to the interested listeners;\n\n2. Steal: Captures the TCP data from a port, and forwards it to the local process, see [`steal`](##steal);\n\n### Minimal `incoming` config\n\n```json { \"feature\": { \"network\": { \"incoming\": \"steal\" } } } ```\n\n### Advanced `incoming` config\n\n```json { \"feature\": { \"network\": { \"incoming\": { \"mode\": \"steal\", \"http_filter\": { \"header_filter\": \"host: api\\..+\" }, \"port_mapping\": [[ 7777, 8888 ]], \"ignore_localhost\": false, \"ignore_ports\": [9999, 10000] \"listen_ports\": [[80, 8111]] } } } } ```",
"anyOf": [
{
"anyOf": [
{
"$ref": "#/definitions/IncomingMode"
},
{
"type": "null"
}
]
},
{
"$ref": "#/definitions/IncomingAdvancedFileConfig"
}
]
},
"IncomingMode": {
"description": "Allows selecting between mirrorring or stealing traffic.\n\nCan be set to either `\"mirror\"` (default), `\"steal\"` or `\"off\"`.\n\n- `\"mirror\"`: Sniffs on TCP port, and send a copy of the data to listeners. - `\"off\"`: Disables the incoming network feature. - `\"steal\"`: Supports 2 modes of operation:\n\n1. Port traffic stealing: Steals all TCP data from a port, which is selected whenever the user listens in a TCP socket (enabling the feature is enough to make this work, no additional configuration is needed);\n\n2. HTTP traffic stealing: Steals only HTTP traffic, mirrord tries to detect if the incoming data on a port is HTTP (in a best-effort kind of way, not guaranteed to be HTTP), and steals the traffic on the port if it is HTTP;",
"oneOf": [
{
"description": "<!--${internal}--> ### mirror\n\nSniffs on TCP port, and send a copy of the data to listeners.",
"type": "string",
"enum": [
"mirror"
]
},
{
"description": "<!--${internal}--> ### steal\n\nStealer supports 2 modes of operation:\n\n1. Port traffic stealing: Steals all TCP data from a port, which is selected whenever the user listens in a TCP socket (enabling the feature is enough to make this work, no additional configuration is needed);\n\n2. HTTP traffic stealing: Steals only HTTP traffic, mirrord tries to detect if the incoming data on a port is HTTP (in a best-effort kind of way, not guaranteed to be HTTP), and steals the traffic on the port if it is HTTP;",
"type": "string",
"enum": [
"steal"
]
},
{
"description": "<!--${internal}--> ### Off\n\nDisables the incoming network feature.",
"type": "string",
"enum": [
"off"
]
}
]
},
"InternalProxyFileConfig": {
"description": "Configuration for the internal proxy mirrord spawns for each local mirrord session that local layers use to connect to the remote agent\n\nThis is seldom used, but if you get `ConnectionRefused` errors, you might want to increase the timeouts a bit.\n\n```json { \"internal_proxy\": { \"start_idle_timeout\": 30, \"idle_timeout\": 5, } } ```",
"type": "object",
"properties": {
"idle_timeout": {
"title": "internal_proxy.idle_timeout {#agent-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 { \"internal_proxy\": { \"idle_timeout\": 30 } } ```",
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0.0
},
"start_idle_timeout": {
"title": "internal_proxy.start_idle_timeout {#agent-start_idle_timeout}",
"description": "How much time to wait for the first connection to the 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 proxy.\n\n```json { \"internal_proxy\": { \"start_idle_timeout\": 60 } } ```",
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0.0
}
},
"additionalProperties": false
},
"LinuxCapability": {
"type": "string",
"enum": [
"SYS_ADMIN",
"SYS_PTRACE",
"NET_RAW",
"NET_ADMIN"
]
},
"NetworkFileConfig": {
"description": "Controls mirrord network operations.\n\nSee the network traffic [reference](https://mirrord.dev/docs/reference/traffic/) for more details.\n\n```json { \"feature\": { \"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 } } } ```",
"type": "object",
"properties": {
"dns": {
"title": "feature.network.dns {#feature-network-dns}",
"description": "Resolve DNS via the remote pod.\n\nDefaults to `true`.",
"type": [
"boolean",
"null"
]
},
"incoming": {
"title": "feature.network.incoming {#feature-network-incoming}",
"anyOf": [
{
"$ref": "#/definitions/ToggleableConfig_for_IncomingFileConfig"
},
{
"type": "null"
}
]
},
"outgoing": {
"title": "feature.network.outgoing {#feature-network-outgoing}",
"anyOf": [
{
"$ref": "#/definitions/ToggleableConfig_for_OutgoingFileConfig"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"OutgoingFileConfig": {
"description": "Tunnel outgoing network operations through mirrord.\n\nSee the outgoing [reference](https://mirrord.dev/docs/reference/traffic/#outgoing) for more details.\n\nThe `remote` and `local` config for this feature are **mutually** exclusive.\n\n```json { \"feature\": { \"network\": { \"outgoing\": { \"tcp\": true, \"udp\": true, \"ignore_localhost\": false, \"filter\": { \"local\": [\"tcp://1.1.1.0/24:1337\", \"1.1.5.0/24\", \"google.com\", \":53\"] }, \"unix_streams\": \"bear.+\" } } } } ```",
"type": "object",
"properties": {
"filter": {
"title": "feature.network.outgoing.filter {#feature.network.outgoing.filter}",
"description": "Unstable: the precise syntax of this config is subject to change.",
"anyOf": [
{
"$ref": "#/definitions/OutgoingFilterConfig"
},
{
"type": "null"
}
]
},
"ignore_localhost": {
"title": "feature.network.outgoing.ignore_localhost {#feature.network.outgoing.ignore_localhost}",
"description": "Defaults to `false`.",
"type": [
"boolean",
"null"
]
},
"tcp": {
"title": "feature.network.outgoing.tcp {#feature.network.outgoing.tcp}",
"description": "Defaults to `true`.",
"type": [
"boolean",
"null"
]
},
"udp": {
"title": "feature.network.outgoing.udp {#feature.network.outgoing.udp}",
"description": "Defaults to `true`.",
"type": [
"boolean",
"null"
]
},
"unix_streams": {
"title": "feature.network.outgoing.unix_streams {#feature.network.outgoing.unix_streams}",
"description": "Connect to these unix streams remotely (and to all other paths locally).\n\nYou can either specify a single value or an array of values. Each value is interpreted as a regular expression ([Supported Syntax](https://docs.rs/regex/1.7.1/regex/index.html#syntax)).\n\nWhen your application connects to a unix socket, the target address will be converted to a string (non-utf8 bytes are replaced by a placeholder character) and matched against the set of regexes specified here. If there is a match, mirrord will connect your application with the target unix socket address on the target pod. Otherwise, it will leave the connection to happen locally on your machine.",
"anyOf": [
{
"$ref": "#/definitions/VecOrSingle_for_String"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"OutgoingFilterConfig": {
"description": "List of addresses/ports/subnets that should be sent 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 outgoing traffic is sent from the remote pod (which is the default behavior when you enable outgoing traffic), or from the local app (default when you have outgoing traffic disabled).\n\nTakes a list of values, such as:\n\n- Only UDP traffic on subnet `1.1.1.0/24` on port 1337 will go through the remote pod.\n\n```json { \"remote\": [\"udp://1.1.1.0/24:1337\"] } ```\n\n- Only UDP and TCP traffic on resolved address of `google.com` on port `1337` and `7331` will go through the remote pod. ```json { \"remote\": [\"google.com:1337\", \"google.com:7331\"] } ```\n\n- Only TCP traffic on `localhost` on port 1337 will go through the local app, the rest will be emmited remotely in the cluster.\n\n```json { \"local\": [\"tcp://localhost:1337\"] } ```\n\n- Only outgoing traffic on port `1337` and `7331` will go through the local app. ```json { \"local\": [\":1337\", \":7331\"] } ```\n\nValid values follow this pattern: `[protocol]://[name|address|subnet/mask]:[port]`.",
"oneOf": [
{
"description": "Traffic that matches what's 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": "Traffic that matches what's 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
}
]
},
"PodTarget": {
"description": "<!--${internal}--> Mirror the pod specified by [`PodTarget::pod`].",
"type": "object",
"required": [
"pod"
],
"properties": {
"container": {
"type": [
"string",
"null"
]
},
"pod": {
"description": "<!--${internal}--> Pod to mirror.",
"type": "string"
}
},
"additionalProperties": false
},
"PortList": {
"description": "<!--${internal}--> Helper struct for setting up ports configuration (part of the HTTP traffic stealer feature).\n\nDefaults to a list of ports `[80, 8080]`.\n\nWe use this to allow implementing a custom [`Default`] initialization, as the [`MirrordConfig`] macro (currently) doesn't support more intricate expressions.",
"allOf": [
{
"$ref": "#/definitions/VecOrSingle_for_uint16"
}
]
},
"RolloutTarget": {
"description": "<!--${internal}--> Mirror the rollout specified by [`RolloutTarget::rollout`].",
"type": "object",
"required": [
"rollout"
],
"properties": {
"container": {
"type": [
"string",
"null"
]
},
"rollout": {
"description": "<!--${internal}--> Rollout to mirror.",
"type": "string"
}
},
"additionalProperties": false
},
"Target": {
"description": "<!--${internal}--> ## path\n\nSpecifies the running pod (or deployment) to mirror.\n\nSupports: - `pod/{sample-pod}`; - `podname/{sample-pod}`; - `deployment/{sample-deployment}`; - `container/{sample-container}`; - `containername/{sample-container}`.",
"anyOf": [
{
"description": "<!--${internal}--> Mirror a deployment.",
"allOf": [
{
"$ref": "#/definitions/DeploymentTarget"