From 52b0cf43ca779da37af09cd0a550b1f928bc8eb9 Mon Sep 17 00:00:00 2001 From: Joshua Casey Date: Wed, 7 Jun 2023 18:07:43 -0500 Subject: [PATCH] Fix godoc --- internal/certauthority/certauthority.go | 8 ++++---- internal/concierge/server/server.go | 15 ++++++++------- internal/config/concierge/config.go | 4 ++-- internal/config/concierge/types.go | 6 +++--- internal/controllerlib/manager.go | 6 +++--- .../oidc/provider/federation_domain_issuer.go | 9 +++++++-- site/content/docs/howto/install-supervisor.md | 2 +- 7 files changed, 28 insertions(+), 22 deletions(-) diff --git a/internal/certauthority/certauthority.go b/internal/certauthority/certauthority.go index 9fcfdcfb..ab9e086d 100644 --- a/internal/certauthority/certauthority.go +++ b/internal/certauthority/certauthority.go @@ -1,4 +1,4 @@ -// Copyright 2020-2021 the Pinniped contributors. All Rights Reserved. +// Copyright 2020-2023 the Pinniped contributors. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 // Package certauthority implements a simple x509 certificate authority suitable for use in an aggregated API service. @@ -179,13 +179,13 @@ func (c *CA) IssueServerCert(dnsNames []string, ips []net.IP, ttl time.Duration) return c.issueCert(x509.ExtKeyUsageServerAuth, pkix.Name{}, dnsNames, ips, ttl) } -// Similar to IssueClientCert, but returning the new cert as a pair of PEM-formatted byte slices +// IssueClientCertPEM is similar to IssueClientCert, but returns the new cert as a pair of PEM-formatted byte slices // for the certificate and private key. func (c *CA) IssueClientCertPEM(username string, groups []string, ttl time.Duration) ([]byte, []byte, error) { return toPEM(c.IssueClientCert(username, groups, ttl)) } -// Similar to IssueServerCert, but returning the new cert as a pair of PEM-formatted byte slices +// IssueServerCertPEM is similar to IssueServerCert, but returns the new cert as a pair of PEM-formatted byte slices // for the certificate and private key. func (c *CA) IssueServerCertPEM(dnsNames []string, ips []net.IP, ttl time.Duration) ([]byte, []byte, error) { return toPEM(c.IssueServerCert(dnsNames, ips, ttl)) @@ -260,7 +260,7 @@ func toPEM(cert *tls.Certificate, err error) ([]byte, []byte, error) { return certPEM, keyPEM, nil } -// Encode a tls.Certificate into a private key PEM and a cert chain PEM. +// ToPEM encodes a tls.Certificate into a private key PEM and a cert chain PEM. func ToPEM(cert *tls.Certificate) ([]byte, []byte, error) { // Encode the certificate(s) to PEM. certPEMBlocks := make([][]byte, 0, len(cert.Certificate)) diff --git a/internal/concierge/server/server.go b/internal/concierge/server/server.go index 906a727d..a3ede977 100644 --- a/internal/concierge/server/server.go +++ b/internal/concierge/server/server.go @@ -1,4 +1,4 @@ -// Copyright 2020-2022 the Pinniped contributors. All Rights Reserved. +// Copyright 2020-2023 the Pinniped contributors. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 // Package server is the command line entry point for pinniped-concierge. @@ -118,17 +118,17 @@ func (a *App) runServer(ctx context.Context) error { // This cert provider will provide certs to the API server and will // be mutated by a controller to keep the certs up to date with what - // is stored in a k8s Secret. Therefore it also effectively acting as - // an in-memory cache of what is stored in the k8s Secret, helping to - // keep incoming requests fast. + // is stored in a k8s Secret. Therefore, it acts as an in-memory cache + // of what is stored in the k8s Secret, helping to keep incoming requests + // fast. dynamicServingCertProvider := dynamiccert.NewServingCert("concierge-serving-cert") // This cert provider will be used to provide the Kube signing key to the - // cert issuer used to issue certs to Pinniped clients wishing to login. + // cert issuer used to issue certs to Pinniped clients wishing to log in. dynamicSigningCertProvider := dynamiccert.NewCA("concierge-kube-signing-cert") // This cert provider will be used to provide the impersonation proxy signing key to the - // cert issuer used to issue certs to Pinniped clients wishing to login. + // cert issuer used to issue certs to Pinniped clients wishing to log in. impersonationProxySigningCertProvider := dynamiccert.NewCA("impersonation-proxy-signing-cert") // Get the "real" name of the login concierge API group (i.e., the API group name with the @@ -256,7 +256,8 @@ func getAggregatedAPIServerConfig( return apiServerConfig, nil } -func main() error { // return an error instead of plog.Fatal to allow defer statements to run +// main returns an error instead of calling plog.Fatal to allow defer statements to run +func main() error { defer plog.Setup()() // Dump out the time since compile (mostly useful for benchmarking our local development cycle latency). diff --git a/internal/config/concierge/config.go b/internal/config/concierge/config.go index 9a4e6aea..c0881a05 100644 --- a/internal/config/concierge/config.go +++ b/internal/config/concierge/config.go @@ -1,4 +1,4 @@ -// Copyright 2020-2022 the Pinniped contributors. All Rights Reserved. +// Copyright 2020-2023 the Pinniped contributors. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 // Package concierge contains functionality to load/store Config's from/to @@ -35,7 +35,7 @@ const ( impersonationProxyPortDefault = 8444 ) -// FromPath loads an Config from a provided local file path, inserts any +// FromPath loads a Config from a provided local file path, inserts any // defaults (from the Config documentation), and verifies that the config is // valid (per the Config documentation). // diff --git a/internal/config/concierge/types.go b/internal/config/concierge/types.go index f444dc82..6e818704 100644 --- a/internal/config/concierge/types.go +++ b/internal/config/concierge/types.go @@ -1,11 +1,11 @@ -// Copyright 2020-2022 the Pinniped contributors. All Rights Reserved. +// Copyright 2020-2023 the Pinniped contributors. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 package concierge import "go.pinniped.dev/internal/plog" -// Config contains knobs to setup an instance of the Pinniped Concierge. +// Config contains knobs to set up an instance of the Pinniped Concierge. type Config struct { DiscoveryInfo DiscoveryInfoSpec `json:"discovery"` APIConfig APIConfigSpec `json:"api"` @@ -21,7 +21,7 @@ type Config struct { } // DiscoveryInfoSpec contains configuration knobs specific to -// pinniped's publishing of discovery information. These values can be +// Pinniped's publishing of discovery information. These values can be // viewed as overrides, i.e., if these are set, then Pinniped will // publish these values in its discovery document instead of the ones it finds. type DiscoveryInfoSpec struct { diff --git a/internal/controllerlib/manager.go b/internal/controllerlib/manager.go index d0babbbe..69647fbb 100644 --- a/internal/controllerlib/manager.go +++ b/internal/controllerlib/manager.go @@ -1,4 +1,4 @@ -// Copyright 2020 the Pinniped contributors. All Rights Reserved. +// Copyright 2020-2023 the Pinniped contributors. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 package controllerlib @@ -39,8 +39,8 @@ func (c *controllerManager) WithController(controller Controller, workers int) M return c } -// Start will run all managed controllers and block until all controllers shutdown. -// When the context passed is cancelled, all controllers are signalled to shutdown. +// Start will run all managed controllers and block until all controllers have shut down. +// When the context passed is cancelled, all controllers are signalled to shut down. func (c *controllerManager) Start(ctx context.Context) { var wg sync.WaitGroup wg.Add(len(c.controllers)) diff --git a/internal/oidc/provider/federation_domain_issuer.go b/internal/oidc/provider/federation_domain_issuer.go index be683c69..a5f19f8c 100644 --- a/internal/oidc/provider/federation_domain_issuer.go +++ b/internal/oidc/provider/federation_domain_issuer.go @@ -1,4 +1,4 @@ -// Copyright 2020 the Pinniped contributors. All Rights Reserved. +// Copyright 2020-2023 the Pinniped contributors. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 package provider @@ -11,7 +11,7 @@ import ( "go.pinniped.dev/internal/constable" ) -// FederationDomainIssuer represents all of the settings and state for a downstream OIDC provider +// FederationDomainIssuer represents all the settings and state for a downstream OIDC provider // as defined by a FederationDomain. type FederationDomainIssuer struct { issuer string @@ -19,6 +19,8 @@ type FederationDomainIssuer struct { issuerPath string } +// NewFederationDomainIssuer returns a FederationDomainIssuer. +// Performs validation, and returns any error from validation. func NewFederationDomainIssuer(issuer string) (*FederationDomainIssuer, error) { p := FederationDomainIssuer{issuer: issuer} err := p.validate() @@ -64,14 +66,17 @@ func (p *FederationDomainIssuer) validate() error { return nil } +// Issuer returns the issuer func (p *FederationDomainIssuer) Issuer() string { return p.issuer } +// IssuerHost returns the issuerHost func (p *FederationDomainIssuer) IssuerHost() string { return p.issuerHost } +// IssuerPath returns the issuerPath func (p *FederationDomainIssuer) IssuerPath() string { return p.issuerPath } diff --git a/site/content/docs/howto/install-supervisor.md b/site/content/docs/howto/install-supervisor.md index 15c38766..376e2a72 100644 --- a/site/content/docs/howto/install-supervisor.md +++ b/site/content/docs/howto/install-supervisor.md @@ -59,7 +59,7 @@ Pinniped uses [ytt](https://carvel.dev/ytt/) from [Carvel](https://carvel.dev/) 1. Customize configuration parameters: - See the [default values](http://github.com/vmware-tanzu/pinniped/tree/main/deploy/supervisor/values.yaml) for documentation about individual configuration parameters. - For example, you can change the number of Concierge pods by setting `replicas` or apply custom annotations to the impersonation proxy service using `impersonation_proxy_spec`. + For example, you can change the number of Supervisor pods by setting `replicas` or install into a non-default namespace using `into_namespace`. - In a different directory, create a new YAML file to contain your site-specific configuration. For example, you might call this file `site/dev-env.yaml`.