diff --git a/docs/usage/advanced/podman.md b/docs/usage/advanced/podman.md index cb5edb53fb..2432cce393 100644 --- a/docs/usage/advanced/podman.md +++ b/docs/usage/advanced/podman.md @@ -107,7 +107,7 @@ Or start an already existing podman machine podman machine start ``` -Grab connection details +Grab connection details ``` podman system connection ls @@ -162,7 +162,11 @@ true ## Creating local registries -Because Podman does not have a default "bridge" network, you have to specify a network using the `--default-network` flag when creating a local registry: +Because Podman does not have a default "bridge" network, you have to specify a network to use when creating a local registry. + +### Using the CLI + +In the CLI, you can use the `--default-network` flag to specify a network for the registry: ```bash k3d registry create --default-network podman mycluster-registry @@ -180,3 +184,18 @@ k3d cluster create --registry-use mycluster-registry mycluster !!! note "Missing cpuset cgroup controller" If you experince an error regarding missing cpuset cgroup controller, ensure the user unit `xdg-document-portal.service` is disabled by running `systemctl --user stop xdg-document-portal.service`. See [this issue](https://github.com/systemd/systemd/issues/18293#issuecomment-831397578) +### Using the config file + +If you're using a configuration file to create your cluster, you can use the `registries.create.network` field to specify the network for the registry. + +```yaml +apiVersion: k3d.io/v1alpha5 +kind: Simple + +... + +registries: + create: + name: mycluster-registry + network: podman +``` diff --git a/docs/usage/configfile.md b/docs/usage/configfile.md index c1ce60f2e5..cbefc04fb8 100644 --- a/docs/usage/configfile.md +++ b/docs/usage/configfile.md @@ -5,7 +5,7 @@ The config file feature is **available as of k3d v4.0.0** ## Introduction !!! info "Syntax & Semantics" - The options defined in the config file are not 100% the same as the CLI flags. + The options defined in the config file are not 100% the same as the CLI flags. This concerns naming and style/usage/structure, e.g. - `--api-port` is split up into a field named `kubeAPI` that has 3 different "child fields" (`host`, `hostIP` and `hostPort`) @@ -36,13 +36,13 @@ kind: Simple ## Config Options -The configuration options for k3d are continuously evolving and so is the config file (syntax) itself. +The configuration options for k3d are continuously evolving and so is the config file (syntax) itself. Currently, the config file is still in an Alpha-State, meaning, that it is subject to change anytime (though we try to keep breaking changes low). !!! info "Validation via JSON-Schema" - k3d uses a [JSON-Schema](https://json-schema.org/) to describe the expected format and fields of the configuration file. - This schema is also used to [validate](https://github.com/xeipuuv/gojsonschema#validation) a user-given config file. - This JSON-Schema can be found in the specific config version sub-directory in the repository (e.g. [here for `v1alpha5`](https://github.com/k3d-io/k3d/blob/main/pkg/config/v1alpha5/schema.json)) and could be used to lookup supported fields or by linters to validate the config file, e.g. in your code editor. + k3d uses a [JSON-Schema](https://json-schema.org/) to describe the expected format and fields of the configuration file. + This schema is also used to [validate](https://github.com/xeipuuv/gojsonschema#validation) a user-given config file. + This JSON-Schema can be found in the specific config version sub-directory in the repository (e.g. [here for `v1alpha5`](https://github.com/k3d-io/k3d/blob/main/pkg/config/v1alpha5/schema.json)) and could be used to lookup supported fields or by linters to validate the config file, e.g. in your code editor. ### All Options: Example @@ -95,6 +95,7 @@ registries: # define how registries should be created or used name: registry.localhost host: "0.0.0.0" hostPort: "5000" + network: k3d-network # use a network other than the default "bridge" network proxy: # omit this to have a "normal" registry, set this to create a registry proxy (pull-through cache) remoteURL: https://registry-1.docker.io # mirror the DockerHub registry username: "" # unauthenticated @@ -110,7 +111,7 @@ registries: # define how registries should be created or used - http://my.company.registry:5000 hostAliases: # /etc/hosts style entries to be injected into /etc/hosts in the node containers and in the NodeHosts section in CoreDNS - ip: 1.2.3.4 - hostnames: + hostnames: - my.host.local - that.other.local - ip: 1.1.1.1 @@ -153,18 +154,18 @@ options: ## Tips -- k3d [expands environment variables](https://pkg.go.dev/os#ExpandEnv) (`$VAR` or `${VAR}`) unconditionally in the config file, even before processing it in any way. +- k3d [expands environment variables](https://pkg.go.dev/os#ExpandEnv) (`$VAR` or `${VAR}`) unconditionally in the config file, even before processing it in any way. ## Config File vs. CLI Flags -k3d uses [`Cobra`](https://github.com/spf13/cobra) and [`Viper`](https://github.com/spf13/viper) for CLI and general config handling respectively. +k3d uses [`Cobra`](https://github.com/spf13/cobra) and [`Viper`](https://github.com/spf13/viper) for CLI and general config handling respectively. This automatically introduces a "config option order of priority" ([precedence order](https://github.com/spf13/viper#why-viper)): !!! info "Config Precedence Order" - Source: [spf13/viper#why-viper](https://github.com/spf13/viper#why-viper) + Source: [spf13/viper#why-viper](https://github.com/spf13/viper#why-viper) >Internal Setting > **CLI Flag** > Environment Variable > **Config File** > (k/v store >) Defaults -This means, that you can define e.g. a "base configuration file" with settings that you share across different clusters and override only the fields that differ between those clusters in your CLI flags/arguments. +This means, that you can define e.g. a "base configuration file" with settings that you share across different clusters and override only the fields that differ between those clusters in your CLI flags/arguments. For example, you use the same config file to create three clusters which only have different names and `kubeAPI` (`--api-port`) settings. ## References diff --git a/pkg/config/config_test.go b/pkg/config/config_test.go index 3f387fcfdc..0f8c4faa70 100644 --- a/pkg/config/config_test.go +++ b/pkg/config/config_test.go @@ -334,3 +334,54 @@ func TestReadSimpleConfigRegistries(t *testing.T) { t.Errorf("Actual representation\n%+v\ndoes not match expected representation\n%+v\nDiff:\n%+v", readConfig, expectedConfig, diff) } } + +func TestReadSimpleConfigRegistriesWithNetwork(t *testing.T) { + exposedAPI := conf.SimpleExposureOpts{} + exposedAPI.HostIP = "0.0.0.0" + exposedAPI.HostPort = "6443" + + expectedConfig := conf.SimpleConfig{ + TypeMeta: configtypes.TypeMeta{ + APIVersion: "k3d.io/v1alpha5", + Kind: "Simple", + }, + ObjectMeta: configtypes.ObjectMeta{ + Name: "test", + }, + Servers: 1, + Agents: 1, + Registries: conf.SimpleConfigRegistries{ + Create: &conf.SimpleConfigRegistryCreateConfig{ + Name: "registry.localhost", + Host: "0.0.0.0", + HostPort: "5001", + Network: "k3d-test-network", + }, + }, + } + + cfgFile := "./test_assets/config_test_registries_2.yaml" + + config := viper.New() + config.SetConfigFile(cfgFile) + + // try to read config into memory (viper map structure) + if err := config.ReadInConfig(); err != nil { + if _, ok := err.(viper.ConfigFileNotFoundError); ok { + t.Error(err) + } + // config file found but some other error happened + t.Error(err) + } + + readConfig, err := FromViper(config) + if err != nil { + t.Error(err) + } + + t.Logf("\n========== Read Config ==========\n%+v\n=================================\n", readConfig) + + if diff := deep.Equal(readConfig, expectedConfig); diff != nil { + t.Errorf("Actual representation\n%+v\ndoes not match expected representation\n%+v\nDiff:\n%+v", readConfig, expectedConfig, diff) + } +} diff --git a/pkg/config/test_assets/config_test_registries_2.yaml b/pkg/config/test_assets/config_test_registries_2.yaml new file mode 100644 index 0000000000..85dfac12ad --- /dev/null +++ b/pkg/config/test_assets/config_test_registries_2.yaml @@ -0,0 +1,12 @@ +apiVersion: k3d.io/v1alpha5 +kind: Simple +metadata: + name: test +servers: 1 +agents: 1 +registries: + create: + name: registry.localhost + host: "0.0.0.0" + hostPort: "5001" + network: "k3d-test-network" diff --git a/pkg/config/transform.go b/pkg/config/transform.go index 12ca8b49b9..86781c33f0 100644 --- a/pkg/config/transform.go +++ b/pkg/config/transform.go @@ -340,6 +340,7 @@ func TransformSimpleToClusterConfig(ctx context.Context, runtime runtimes.Runtim Host: regName, Image: image, ExposureOpts: *regPort, + Network: simpleConfig.Registries.Create.Network, Volumes: simpleConfig.Registries.Create.Volumes, Options: k3d.RegistryOptions{ Proxy: simpleConfig.Registries.Create.Proxy, diff --git a/pkg/config/v1alpha5/schema.json b/pkg/config/v1alpha5/schema.json index c4eaa6ee4f..e3ff40cdb7 100644 --- a/pkg/config/v1alpha5/schema.json +++ b/pkg/config/v1alpha5/schema.json @@ -335,6 +335,14 @@ ], "default": "random" }, + "network": { + "type": "string", + "examples": [ + "bridge", + "k3d-network" + ], + "default": "bridge" + }, "image": { "type": "string", "examples": [ diff --git a/pkg/config/v1alpha5/types.go b/pkg/config/v1alpha5/types.go index e681062021..86e14d850d 100644 --- a/pkg/config/v1alpha5/types.go +++ b/pkg/config/v1alpha5/types.go @@ -95,6 +95,7 @@ type SimpleConfigRegistryCreateConfig struct { Name string `mapstructure:"name" json:"name,omitempty"` Host string `mapstructure:"host" json:"host,omitempty"` HostPort string `mapstructure:"hostPort" json:"hostPort,omitempty"` + Network string `mapstructure:"network" json:"network,omitempty"` Image string `mapstructure:"image" json:"image,omitempty"` Proxy k3d.RegistryProxy `mapstructure:"proxy" json:"proxy,omitempty"` Volumes []string `mapstructure:"volumes" json:"volumes,omitempty"`