dev-docs: Go package docs (#958)

* Remove unused package * Add Go package docs to most packages Signed-off-by: Daniel Weiße <[email protected]> Signed-off-by: Fabian Kammel <[email protected]> Signed-off-by: Paul Meyer <[email protected]> Co-authored-by: Paul Meyer <[email protected]> Co-authored-by: Fabian Kammel <[email protected]>
edgelesssys · Jan 19, 2023 · 690b50b · 690b50b
1 parent b774072
commit 690b50b
Show file tree

Hide file tree

Showing 118 changed files with 735 additions and 750 deletions.
diff --git a/bootstrapper/README.md b/bootstrapper/README.md
@@ -9,7 +9,7 @@ The bootstrapper has two active components:
 
 ## Init Flow
 
-The InitServer is a gRPC server that is listining for initialization requests.
+The InitServer is a gRPC server that is listening for initialization requests.
 The first instance needs to be initialized by the user, see the [initproto](./initproto)
 for a description of the initialization protocol. The client that talks to this server
 is part of Constellation's CLI.

diff --git a/bootstrapper/cmd/bootstrapper/main.go b/bootstrapper/cmd/bootstrapper/main.go
@@ -16,7 +16,7 @@ import (
 	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/helm"
 	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/kubernetes"
 	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/kubernetes/k8sapi"
-	kubewaiter "github.com/edgelesssys/constellation/v2/bootstrapper/internal/kubernetes/kubeWaiter"
+	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/kubernetes/kubewaiter"
 	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/logging"
 	"github.com/edgelesssys/constellation/v2/internal/atls"
 	"github.com/edgelesssys/constellation/v2/internal/attestation/aws"

diff --git a/bootstrapper/internal/certificate/certificate.go b/bootstrapper/internal/certificate/certificate.go
@@ -4,16 +4,40 @@ Copyright (c) Edgeless Systems GmbH
 SPDX-License-Identifier: AGPL-3.0-only
 */
 
+// Package certificate provides functions to create a certificate request and matching private key.
 package certificate
 
 import (
 	"crypto/ecdsa"
 	"crypto/elliptic"
 	"crypto/rand"
 	"crypto/x509"
+	"crypto/x509/pkix"
 	"encoding/pem"
+	"net"
+
+	"k8s.io/kubernetes/cmd/kubeadm/app/constants"
+)
+
+const (
+	// CertificateFilename is the path to the kubelets certificate.
+	CertificateFilename = "/run/state/kubelet/pki/kubelet-client-crt.pem"
+	// KeyFilename is the path to the kubelets private key.
+	KeyFilename = "/run/state/kubelet/pki/kubelet-client-key.pem"
 )
 
+// GetKubeletCertificateRequest returns a certificate request and matching private key for the kubelet.
+func GetKubeletCertificateRequest(nodeName string, ips []net.IP) (certificateRequest []byte, privateKey []byte, err error) {
+	csrTemplate := &x509.CertificateRequest{
+		Subject: pkix.Name{
+			Organization: []string{constants.NodesGroup},
+			CommonName:   constants.NodesUserPrefix + nodeName,
+		},
+		IPAddresses: ips,
+	}
+	return GetCertificateRequest(csrTemplate)
+}
+
 // GetCertificateRequest returns a certificate request and matching private key.
 func GetCertificateRequest(csrTemplate *x509.CertificateRequest) (certificateRequest []byte, privateKey []byte, err error) {
 	privK, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)

diff --git a/bootstrapper/internal/clean/clean.go b/bootstrapper/internal/clean/clean.go
@@ -4,6 +4,7 @@ Copyright (c) Edgeless Systems GmbH
 SPDX-License-Identifier: AGPL-3.0-only
 */
 
+// Package clean provides functionality to stop a list of services gracefully and synchronously.
 package clean
 
 import (

diff --git a/bootstrapper/internal/diskencryption/diskencryption.go b/bootstrapper/internal/diskencryption/diskencryption.go
@@ -4,6 +4,12 @@ Copyright (c) Edgeless Systems GmbH
 SPDX-License-Identifier: AGPL-3.0-only
 */
 
+/*
+Package diskencryption handles interaction with a node's state disk.
+
+This package is not thread safe, since libcryptsetup is not thread safe.
+There should only be one instance using this package per process.
+*/
 package diskencryption
 
 import (

diff --git a/bootstrapper/internal/helm/client.go → bootstrapper/internal/helm/helm.go b/bootstrapper/internal/helm/client.go → bootstrapper/internal/helm/helm.go
@@ -4,6 +4,7 @@ Copyright (c) Edgeless Systems GmbH
 SPDX-License-Identifier: AGPL-3.0-only
 */
 
+// Package helm is used to install Constellation microservices and other services during cluster initialization.
 package helm
 
 import (

diff --git a/bootstrapper/internal/helm/client_test.go → bootstrapper/internal/helm/helm_test.go b/bootstrapper/internal/helm/client_test.go → bootstrapper/internal/helm/helm_test.go
diff --git a/bootstrapper/internal/initserver/initserver.go b/bootstrapper/internal/initserver/initserver.go
@@ -4,6 +4,17 @@ Copyright (c) Edgeless Systems GmbH
 SPDX-License-Identifier: AGPL-3.0-only
 */
 
+/*
+# InitServer
+
+The InitServer is one of the two main components of the bootstrapper.
+It is responsible for the initial setup of a node, and the initialization of the Kubernetes cluster.
+
+The InitServer is started on each node, and waits for either a call from the CLI,
+or for the JoinClient to connect to an existing cluster.
+
+If a call from the CLI is received, the InitServer bootstraps the Kubernetes cluster, and stops the JoinClient.
+*/
 package initserver
 
 import (

diff --git a/bootstrapper/internal/joinclient/client.go → ...trapper/internal/joinclient/joinclient.go b/bootstrapper/internal/joinclient/client.go → ...trapper/internal/joinclient/joinclient.go
@@ -4,6 +4,17 @@ Copyright (c) Edgeless Systems GmbH
 SPDX-License-Identifier: AGPL-3.0-only
 */
 
+/*
+# JoinClient
+
+The JoinClient is one of the two main components of the bootstrapper.
+It is responsible for for the initial setup of a node, and joining an existing Kubernetes cluster.
+
+The JoinClient is started on each node, it then continuously checks for an existing cluster to join,
+or for the InitServer to bootstrap a new cluster.
+
+If the JoinClient finds an existing cluster, it will attempt to join it as either a control-plane or a worker node.
+*/
 package joinclient
 
 import (
@@ -16,8 +27,8 @@ import (
 	"sync"
 	"time"
 
+	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/certificate"
 	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/diskencryption"
-	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/kubelet"
 	"github.com/edgelesssys/constellation/v2/internal/attestation"
 	"github.com/edgelesssys/constellation/v2/internal/cloud/metadata"
 	"github.com/edgelesssys/constellation/v2/internal/constants"
@@ -201,7 +212,7 @@ func (c *JoinClient) join(serviceEndpoint string) error {
 	ctx, cancel := c.timeoutCtx()
 	defer cancel()
 
-	certificateRequest, kubeletKey, err := kubelet.GetCertificateRequest(c.nodeName, c.validIPs)
+	certificateRequest, kubeletKey, err := certificate.GetKubeletCertificateRequest(c.nodeName, c.validIPs)
 	if err != nil {
 		return err
 	}
@@ -267,10 +278,10 @@ func (c *JoinClient) startNodeAndJoin(ticket *joinproto.IssueJoinTicketResponse,
 			return fmt.Errorf("writing control plane files: %w", err)
 		}
 	}
-	if err := c.fileHandler.Write(kubelet.CertificateFilename, ticket.KubeletCert, file.OptMkdirAll); err != nil {
+	if err := c.fileHandler.Write(certificate.CertificateFilename, ticket.KubeletCert, file.OptMkdirAll); err != nil {
 		return fmt.Errorf("writing kubelet certificate: %w", err)
 	}
-	if err := c.fileHandler.Write(kubelet.KeyFilename, kubeletKey, file.OptMkdirAll); err != nil {
+	if err := c.fileHandler.Write(certificate.KeyFilename, kubeletKey, file.OptMkdirAll); err != nil {
 		return fmt.Errorf("writing kubelet key: %w", err)
 	}
 

diff --git a/...rapper/internal/joinclient/client_test.go → ...er/internal/joinclient/joinclient_test.go b/...rapper/internal/joinclient/client_test.go → ...er/internal/joinclient/joinclient_test.go
diff --git a/bootstrapper/internal/kubelet/kubelet.go b/bootstrapper/internal/kubelet/kubelet.go
diff --git a/bootstrapper/internal/kubernetes/k8sapi/k8sapi.go b/bootstrapper/internal/kubernetes/k8sapi/k8sapi.go
@@ -0,0 +1,8 @@
+/*
+Copyright (c) Edgeless Systems GmbH
+
+SPDX-License-Identifier: AGPL-3.0-only
+*/
+
+// Package k8sapi is used to interact with the Kubernetes API to create or update required resources.
+package k8sapi
diff --git a/bootstrapper/internal/kubernetes/k8sapi/k8sutil.go b/bootstrapper/internal/kubernetes/k8sapi/k8sutil.go
@@ -22,7 +22,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/kubelet"
+	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/certificate"
 	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/kubernetes/k8sapi/resources"
 	"github.com/edgelesssys/constellation/v2/internal/constants"
 	"github.com/edgelesssys/constellation/v2/internal/role"
@@ -345,11 +345,11 @@ func (k *KubernetesUtil) StartKubelet() error {
 // This is necessary because this node does not request a certificate from the join service.
 func (k *KubernetesUtil) createSignedKubeletCert(nodeName string, ips []net.IP) error {
 	// Create CSR
-	certRequestRaw, kubeletKey, err := kubelet.GetCertificateRequest(nodeName, ips)
+	certRequestRaw, kubeletKey, err := certificate.GetKubeletCertificateRequest(nodeName, ips)
 	if err != nil {
 		return err
 	}
-	if err := k.file.Write(kubelet.KeyFilename, kubeletKey, file.OptMkdirAll); err != nil {
+	if err := k.file.Write(certificate.KeyFilename, kubeletKey, file.OptMkdirAll); err != nil {
 		return err
 	}
 
@@ -399,7 +399,7 @@ func (k *KubernetesUtil) createSignedKubeletCert(nodeName string, ips []net.IP)
 		Bytes: certRaw,
 	})
 
-	return k.file.Write(kubelet.CertificateFilename, kubeletCert, file.OptMkdirAll)
+	return k.file.Write(certificate.CertificateFilename, kubeletCert, file.OptMkdirAll)
 }
 
 // createSignedKonnectivityCert manually creates a Kubernetes CA signed certificate for the Konnectivity server.

diff --git a/bootstrapper/internal/kubernetes/k8sapi/kubeadm_config.go b/bootstrapper/internal/kubernetes/k8sapi/kubeadm_config.go
@@ -9,7 +9,7 @@ package k8sapi
 import (
 	"path/filepath"
 
-	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/kubelet"
+	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/certificate"
 	"github.com/edgelesssys/constellation/v2/internal/constants"
 	"github.com/edgelesssys/constellation/v2/internal/kubernetes"
 	corev1 "k8s.io/api/core/v1"
@@ -166,8 +166,8 @@ func (c *KubdeadmConfiguration) InitConfiguration(externalCloudProvider bool, cl
 					Effect: corev1.TaintEffectPreferNoSchedule,
 				},
 			},
-			TLSCertFile:       kubelet.CertificateFilename,
-			TLSPrivateKeyFile: kubelet.KeyFilename,
+			TLSCertFile:       certificate.CertificateFilename,
+			TLSPrivateKeyFile: certificate.KeyFilename,
 		},
 	}
 }

diff --git a/bootstrapper/internal/kubernetes/k8sapi/resources/resources.go b/bootstrapper/internal/kubernetes/k8sapi/resources/resources.go
@@ -0,0 +1,8 @@
+/*
+Copyright (c) Edgeless Systems GmbH
+
+SPDX-License-Identifier: AGPL-3.0-only
+*/
+
+// Package resources contains Kubernetes configs and policies for Constellation.
+package resources
diff --git a/bootstrapper/internal/kubernetes/kubernetes.go b/bootstrapper/internal/kubernetes/kubernetes.go
@@ -4,6 +4,7 @@ Copyright (c) Edgeless Systems GmbH
 SPDX-License-Identifier: AGPL-3.0-only
 */
 
+// Package kubernetes provides functionality to bootstrap a Kubernetes cluster, or join an exiting one.
 package kubernetes
 
 import (
@@ -19,7 +20,7 @@ import (
 	"time"
 
 	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/kubernetes/k8sapi"
-	kubewaiter "github.com/edgelesssys/constellation/v2/bootstrapper/internal/kubernetes/kubeWaiter"
+	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/kubernetes/kubewaiter"
 	"github.com/edgelesssys/constellation/v2/internal/attestation/measurements"
 	"github.com/edgelesssys/constellation/v2/internal/cloud/azureshared"
 	"github.com/edgelesssys/constellation/v2/internal/cloud/cloudprovider"

diff --git a/bootstrapper/internal/kubernetes/kubernetes_test.go b/bootstrapper/internal/kubernetes/kubernetes_test.go
@@ -14,7 +14,7 @@ import (
 	"testing"
 
 	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/kubernetes/k8sapi"
-	kubewaiter "github.com/edgelesssys/constellation/v2/bootstrapper/internal/kubernetes/kubeWaiter"
+	"github.com/edgelesssys/constellation/v2/bootstrapper/internal/kubernetes/kubewaiter"
 	"github.com/edgelesssys/constellation/v2/internal/cloud/metadata"
 	"github.com/edgelesssys/constellation/v2/internal/constants"
 	"github.com/edgelesssys/constellation/v2/internal/deploy/helm"

diff --git a/.../internal/kubernetes/kubeWaiter/waiter.go → ...ernal/kubernetes/kubewaiter/kubewaiter.go b/.../internal/kubernetes/kubeWaiter/waiter.go → ...ernal/kubernetes/kubewaiter/kubewaiter.go
@@ -4,6 +4,7 @@ Copyright (c) Edgeless Systems GmbH
 SPDX-License-Identifier: AGPL-3.0-only
 */
 
+// Package kubewaiter is used to wait for the Kubernetes API to be available.
 package kubewaiter
 
 import (

diff --git a/...rnal/kubernetes/kubeWaiter/waiter_test.go → .../kubernetes/kubewaiter/kubewaiter_test.go b/...rnal/kubernetes/kubeWaiter/waiter_test.go → .../kubernetes/kubewaiter/kubewaiter_test.go
diff --git a/bootstrapper/internal/logging/logger.go b/bootstrapper/internal/logging/logger.go
@@ -4,6 +4,7 @@ Copyright (c) Edgeless Systems GmbH
 SPDX-License-Identifier: AGPL-3.0-only
 */
 
+// Package logging provides an interface for logging information to a non-confidential destination
 package logging
 
 import "io"

diff --git a/bootstrapper/internal/nodelock/nodelock.go b/bootstrapper/internal/nodelock/nodelock.go
@@ -4,6 +4,7 @@ Copyright (c) Edgeless Systems GmbH
 SPDX-License-Identifier: AGPL-3.0-only
 */
 
+// Package nodelock handles locking operations on the node.
 package nodelock
 
 import (

diff --git a/cli/cmd/root.go b/cli/cmd/root.go
@@ -4,6 +4,11 @@ Copyright (c) Edgeless Systems GmbH
 SPDX-License-Identifier: AGPL-3.0-only
 */
 
+/*
+Package cmd is the entrypoint of the Constellation CLI.
+
+Business logic of the CLI shall be implemented in the internal/cmd package.
+*/
 package cmd
 
 import (

diff --git a/cli/internal/cloudcmd/cloudcmd.go b/cli/internal/cloudcmd/cloudcmd.go
@@ -0,0 +1,22 @@
+/*
+Copyright (c) Edgeless Systems GmbH
+
+SPDX-License-Identifier: AGPL-3.0-only
+*/
+
+/*
+Package cloudcmd provides executable command for the CLI.
+
+This package focuses on the interaction with the cloud provider.
+It separates the cloud provider specific code from the rest of the CLI, and
+provides a common interface for all cloud providers.
+
+Exported functions must not be cloud provider specific, but rather take a
+cloudprovider.Provider as an argument.
+
+User interaction happens in the cmd package, and should not happen or pass through
+this package.
+
+The backend to this package is currently provided by the terraform package.
+*/
+package cloudcmd
diff --git a/cli/internal/cmd/cmd.go b/cli/internal/cmd/cmd.go
@@ -0,0 +1,12 @@
+/*
+Copyright (c) Edgeless Systems GmbH
+
+SPDX-License-Identifier: AGPL-3.0-only
+*/
+
+/*
+Package cmd provides the Constellation CLI.
+
+It is responsible for the interaction with the user.
+*/
+package cmd
diff --git a/cli/internal/image/image.go b/cli/internal/image/image.go
@@ -4,6 +4,11 @@ Copyright (c) Edgeless Systems GmbH
 SPDX-License-Identifier: AGPL-3.0-only
 */
 
+/*
+Package image provides helping wrappers around a versionsapi fetcher.
+
+It also enables local image overrides and download of raw images.
+*/
 package image
 
 import (

diff --git a/cli/internal/libvirt/libvirt.go b/cli/internal/libvirt/libvirt.go
@@ -4,6 +4,7 @@ Copyright (c) Edgeless Systems GmbH
 SPDX-License-Identifier: AGPL-3.0-only
 */
 
+// Package libvirt is used to start and stop containerized libvirt instances.
 package libvirt
 
 import (

diff --git a/cli/internal/terraform/terraform.go b/cli/internal/terraform/terraform.go
@@ -4,6 +4,14 @@ Copyright (c) Edgeless Systems GmbH
 SPDX-License-Identifier: AGPL-3.0-only
 */
 
+/*
+Package terraform handles creation/destruction of a Constellation cluster using Terraform.
+
+Since Terraform does not provide a stable Go API, we use the `terraform-exec` package to interact with Terraform.
+
+The Terraform templates are located in the "terraform" subdirectory. The templates are embedded into the CLI binary using `go:embed`.
+On use the relevant template is extracted to the working directory and the user customized variables are written to a `terraform.tfvars` file.
+*/
 package terraform
 
 import (