Skip to content

Commit

Permalink
docs: update go structs with updated format for docgen
Browse files Browse the repository at this point in the history
Updates Go types for compatibility with an external implementation
of docgen.

Signed-off-by: Andrew Rynhard <[email protected]>
  • Loading branch information
andrewrynhard committed May 4, 2024
1 parent 98906ed commit 57e68c8
Show file tree
Hide file tree
Showing 16 changed files with 980 additions and 1,926 deletions.
2 changes: 0 additions & 2 deletions pkg/machinery/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,6 @@
// Package config provides methods to generate and consume Talos configuration.
package config

//go:generate docgen -generate-schema-from-dir types/ -json-schema-output schemas/config.schema.json -version-tag-file ../gendata/data/tag

import "github.com/siderolabs/talos/pkg/machinery/config/config"

// Config defines the interface to access contents of the machine configuration.
Expand Down
2 changes: 1 addition & 1 deletion pkg/machinery/config/generate/init.go
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,7 @@ func (in *Input) init() ([]config.Document, error) {
cluster.AllowSchedulingOnControlPlanes = pointer.To(in.Options.AllowSchedulingOnControlPlanes)
} else {
// backwards compatibility for Talos versions older than 1.2
cluster.AllowSchedulingOnMasters = pointer.To(in.Options.AllowSchedulingOnControlPlanes) //nolint:staticcheck
cluster.AllowSchedulingOnMasters = pointer.To(in.Options.AllowSchedulingOnControlPlanes)
}
}

Expand Down
4 changes: 2 additions & 2 deletions pkg/machinery/config/types/meta/meta.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ package meta

// Meta is a shared meta information for config documents.
type Meta struct {
MetaAPIVersion string `yaml:"apiVersion,omitempty"`
MetaKind string `yaml:"kind"`
MetaAPIVersion string `yaml:"apiVersion,omitempty" docgen:"{'required':true}"`
MetaKind string `yaml:"kind" docgen:"{'required':true}"`
}

// Kind implements config.Document interface.
Expand Down
16 changes: 3 additions & 13 deletions pkg/machinery/config/types/network/default_action_config.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@

package network

//docgen:jsonschema

import (
"github.com/siderolabs/talos/pkg/machinery/config/config"
"github.com/siderolabs/talos/pkg/machinery/config/internal/registry"
Expand Down Expand Up @@ -35,19 +33,11 @@ var (

// DefaultActionConfigV1Alpha1 is a ingress firewall default action configuration document.
//
// examples:
// - value: exampleDefaultActionConfigV1Alpha1()
// alias: NetworkDefaultActionConfig
// schemaRoot: true
// schemaMeta: v1alpha1/NetworkDefaultActionConfig
//docgen:version=v1alpha1
type DefaultActionConfigV1Alpha1 struct {
meta.Meta `yaml:",inline"`
// description: |
// Default action for all not explicitly configured ingress traffic: accept or block.
// values:
// - "accept"
// - "block"
Ingress nethelpers.DefaultAction `yaml:"ingress"`
// The default action for all configured ingress traffic not explicitly defined.
Ingress nethelpers.DefaultAction `yaml:"ingress" docgen:"{'in':'1.7','values':['accept','block']}"`
}

// NewDefaultActionConfigV1Alpha1 creates a new DefaultActionConfig config document.
Expand Down
2 changes: 0 additions & 2 deletions pkg/machinery/config/types/network/network.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,4 @@
// Package network provides network machine configuration documents.
package network

//go:generate docgen -output network_doc.go network.go default_action_config.go port_range.go rule_config.go

//go:generate deep-copy -type DefaultActionConfigV1Alpha1 -type RuleConfigV1Alpha1 -pointer-receiver -header-file ../../../../../hack/boilerplate.txt -o deep_copy.generated.go .
4 changes: 0 additions & 4 deletions pkg/machinery/config/types/network/port_range.go
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,6 @@ import (
)

// PortRange is a port range.
//
//docgen:nodoc
type PortRange struct {
Lo uint16
Hi uint16
Expand Down Expand Up @@ -72,8 +70,6 @@ func (pr PortRange) String() string {
}

// PortRanges is a slice of port ranges.
//
//docgen:nodoc
type PortRanges []PortRange

// Validate the port ranges.
Expand Down
77 changes: 14 additions & 63 deletions pkg/machinery/config/types/network/rule_config.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@

package network

//docgen:jsonschema

import (
"errors"
"fmt"
Expand Down Expand Up @@ -45,85 +43,38 @@ var (

// RuleConfigV1Alpha1 is a network firewall rule config document.
//
// examples:
// - value: exampleRuleConfigV1Alpha1()
// alias: NetworkRuleConfig
// schemaRoot: true
// schemaMeta: v1alpha1/NetworkRuleConfig
//docgen:version=v1alpha1
type RuleConfigV1Alpha1 struct {
meta.Meta `yaml:",inline"`
// description: |
// Name of the config document.
// schemaRequired: true
MetaName string `yaml:"name"`
// description: |
// Port selector defines which ports and protocols on the host are affected by the rule.
PortSelector RulePortSelector `yaml:"portSelector"`
// description: |
// Ingress defines which source subnets are allowed to access the host ports/protocols defined by the `portSelector`.
Ingress IngressConfig `yaml:"ingress" merge:"replace"`
// Name of the config document.
MetaName string `yaml:"name" docgen:"{'in':'1.7','required':true}"`
// The port selector defines which ports and protocols on the host are affected by the rule.
PortSelector RulePortSelector `yaml:"portSelector" docgen:"{'in':'1.7'}"`
// Defines which source subnets are allowed to access the host ports/protocols defined by the `portSelector`.
Ingress IngressConfig `yaml:"ingress" merge:"replace" docgen:"{'in':'1.7'}"`
}

// RulePortSelector is a port selector for the network rule.
type RulePortSelector struct {
// description: |
// Ports defines a list of port ranges or single ports.
// The port ranges are inclusive, and should not overlap.
// examples:
// - value: >
// examplePortRanges1()
// - value: >
// examplePortRanges2()
// schema:
// type: array
// items:
// oneOf:
// - type: integer
// - type: string
Ports PortRanges `yaml:"ports" merge:"replace"`
// description: |
// Protocol defines traffic protocol (e.g. TCP or UDP).
// values:
// - "tcp"
// - "udp"
// - "icmp"
// - "icmpv6"
Protocol nethelpers.Protocol `yaml:"protocol"`
// Defines a list of port ranges or single ports. The port ranges are inclusive, and should not overlap.
Ports PortRanges `yaml:"ports" merge:"replace" docgen:"{'in':'1.7'}"`
// Defines traffic protocol (e.g. TCP or UDP).
Protocol nethelpers.Protocol `yaml:"protocol" docgen:"{'in':'1.7','values':['tcp','udp','icmp','icmpv6']}"`
}

// IngressConfig is a ingress config.
//
//docgen:alias
type IngressConfig []IngressRule

// IngressRule is a ingress rule.
type IngressRule struct {
// description: |
// Subnet defines a source subnet.
// examples:
// - value: >
// netip.MustParsePrefix("10.3.4.0/24")
// - value: >
// netip.MustParsePrefix("2001:db8::/32")
// - value: >
// netip.MustParsePrefix("1.3.4.5/32")
// schema:
// type: string
// pattern: ^[0-9a-f.:]+/\d{1,3}$
Subnet netip.Prefix `yaml:"subnet"`
// description: |
// Except defines a source subnet to exclude from the rule, it gets excluded from the `subnet`.
// schema:
// type: string
// pattern: ^[0-9a-f.:]+/\d{1,3}$
Except Prefix `yaml:"except,omitempty"`
// Defines a source subnet.
Subnet netip.Prefix `yaml:"subnet" docgen:"{'in':'1.7','pattern':'^[0-9a-f.:]+/\d{1,3}$'}"`
Except Prefix `yaml:"except,omitempty" docgen:"{'in':'1.7','pattern':'^[0-9a-f.:]+/\d{1,3}$'}"`
}

// Prefix is a wrapper for netip.Prefix.
//
// It implements IsZero() so that yaml.Marshal correctly skips empty values.
//
//docgen:nodoc
type Prefix struct {
netip.Prefix
}
Expand Down
16 changes: 3 additions & 13 deletions pkg/machinery/config/types/runtime/event_sink.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@

package runtime

//docgen:jsonschema

import (
"fmt"
"net"
Expand Down Expand Up @@ -41,19 +39,11 @@ var (

// EventSinkV1Alpha1 is a event sink config document.
//
// examples:
// - value: exampleEventSinkV1Alpha1()
// alias: EventSinkConfig
// schemaRoot: true
// schemaMeta: v1alpha1/EventSinkConfig
//docgen:version=v1alpha1
type EventSinkV1Alpha1 struct {
meta.Meta `yaml:",inline"`
// description: |
// The endpoint for the event sink as 'host:port'.
// examples:
// - value: >
// "10.3.7.3:2810"
Endpoint string `yaml:"endpoint"`
// The endpoint for the event sink as 'host:port'.
Endpoint string `yaml:"endpoint" docgen:"{'in':'1.7'}"`
}

// NewEventSinkV1Alpha1 creates a new eventsink config document.
Expand Down
2 changes: 0 additions & 2 deletions pkg/machinery/config/types/runtime/extensions/extensions.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,4 @@
// Package extensions provides extensions config documents.
package extensions

//go:generate docgen -output extensions_doc.go extensions.go service_config.go

//go:generate deep-copy -type ServiceConfigV1Alpha1 -pointer-receiver -header-file ../../../../../../hack/boilerplate.txt -o deep_copy.generated.go .
34 changes: 11 additions & 23 deletions pkg/machinery/config/types/runtime/extensions/service_config.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@

package extensions

//docgen:jsonschema

import (
"fmt"

Expand Down Expand Up @@ -40,33 +38,23 @@ var (

// ServiceConfigV1Alpha1 is a extensionserviceconfig document.
//
// examples:
// - value: extensionServiceConfigV1Alpha1()
// alias: ExtensionServiceConfig
// schemaRoot: true
// schemaMeta: v1alpha1/ExtensionServiceConfig
//docgen:version=v1alpha1
type ServiceConfigV1Alpha1 struct {
meta.Meta `yaml:",inline"`
// description: |
// Name of the extension service.
// schemaRequired: true
ServiceName string `yaml:"name"`
// description: |
// The config files for the extension service.
ServiceConfigFiles []ConfigFile `yaml:"configFiles,omitempty"`
// description: |
// The environment for the extension service.
ServiceEnvironment []string `yaml:"environment,omitempty"`
// The name of the extension service.
ServiceName string `yaml:"name" docgen:"{'in':'1.7','required':true}"`
// The config files for the extension service.
ServiceConfigFiles []ConfigFile `yaml:"configFiles,omitempty" docgen:"{'in':'1.7'}"`
// The environment for the extension service.
ServiceEnvironment []string `yaml:"environment,omitempty" docgen:"{'in':'1.7'}"`
}

// ConfigFile is a config file for extension services.
type ConfigFile struct {
// description: |
// The content of the extension service config file.
ConfigFileContent string `yaml:"content"`
// description: |
// The mount path of the extension service config file.
ConfigFileMountPath string `yaml:"mountPath"`
// The content of the extension service config file.
ConfigFileContent string `yaml:"content" docgen:"{'in':'1.7'}"`
// The mount path of the extension service config file.
ConfigFileMountPath string `yaml:"mountPath" docgen:"{'in':'1.7'}"`
}

// NewServicesConfigV1Alpha1 creates a new siderolink config document.
Expand Down
27 changes: 5 additions & 22 deletions pkg/machinery/config/types/runtime/kmsg_log.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@

package runtime

//docgen:jsonschema

import (
"errors"
"net/url"
Expand Down Expand Up @@ -41,28 +39,13 @@ var (

// KmsgLogV1Alpha1 is a event sink config document.
//
// examples:
// - value: exampleKmsgLogV1Alpha1()
// alias: KmsgLogConfig
// schemaRoot: true
// schemaMeta: v1alpha1/KmsgLogConfig
//docgen:version=v1alpha1
type KmsgLogV1Alpha1 struct {
meta.Meta `yaml:",inline"`
// description: |
// Name of the config document.
MetaName string `yaml:"name"`
// description: |
// The URL encodes the log destination.
// The scheme must be tcp:// or udp://.
// The path must be empty.
// The port is required.
// examples:
// - value: >
// "udp://10.3.7.3:2810"
// schema:
// type: string
// pattern: "^(tcp|udp)://"
KmsgLogURL meta.URL `yaml:"url"`
// Name of the config document.
MetaName string `yaml:"name" docgen:"{'in':'1.7'}"`
// Encodes the log destination. The path must be empty and the port is required.
KmsgLogURL meta.URL `yaml:"url" docgen:"{'in':'1.7','pattern':'^(tcp|udp)://'}"`
}

// NewKmsgLogV1Alpha1 creates a new eventsink config document.
Expand Down
2 changes: 0 additions & 2 deletions pkg/machinery/config/types/runtime/runtime.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,4 @@
// Package runtime provides runtime machine configuration documents.
package runtime

//go:generate docgen -output runtime_doc.go runtime.go kmsg_log.go event_sink.go watchdog_timer.go

//go:generate deep-copy -type EventSinkV1Alpha1 -type KmsgLogV1Alpha1 -type WatchdogTimerV1Alpha1 -pointer-receiver -header-file ../../../../../hack/boilerplate.txt -o deep_copy.generated.go .
28 changes: 5 additions & 23 deletions pkg/machinery/config/types/runtime/watchdog_timer.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@

package runtime

//docgen:jsonschema

import (
"fmt"
"net/url"
Expand Down Expand Up @@ -45,29 +43,13 @@ const (

// WatchdogTimerV1Alpha1 is a watchdog timer config document.
//
// examples:
// - value: exampleWatchdogTimerV1Alpha1()
// alias: WatchdogTimerConfig
// schemaRoot: true
// schemaMeta: v1alpha1/WatchdogTimerConfig
//docgen:version=v1alpha1
type WatchdogTimerV1Alpha1 struct {
meta.Meta `yaml:",inline"`
// description: |
// Path to the watchdog device.
// examples:
// - value: >
// "/dev/watchdog0"
WatchdogDevice string `yaml:"device"`
// description: |
// Timeout for the watchdog.
//
// If Talos is unresponsive for this duration, the watchdog will reset the system.
//
// Default value is 1 minute, minimum value is 10 seconds.
// schema:
// type: string
// pattern: ^[-+]?(((\d+(\.\d*)?|\d*(\.\d+)+)([nuµm]?s|m|h))|0)+$
WatchdogTimeout time.Duration `yaml:"timeout,omitempty"`
// The Path to the watchdog device.
WatchdogDevice string `yaml:"device" docgen:"{'in':'1.7'}"`
// The timeout for the watchdog. If Talos is unresponsive for this duration, the watchdog will reset the system.
WatchdogTimeout time.Duration `yaml:"timeout,omitempty" docgen:"{'in':'1.7','default':'1m'}"`
}

// NewWatchdogTimerV1Alpha1 creates a new eventsink config document.
Expand Down
Loading

0 comments on commit 57e68c8

Please sign in to comment.