From 83827a3c5a725cb7884707a59cb1976111c97cb3 Mon Sep 17 00:00:00 2001 From: Tom McLaughlin Date: Sat, 12 Oct 2024 03:55:21 -0700 Subject: [PATCH] sandwich-contexts-kubernetes: more haddocks --- .../Sandwich/Contexts/Kubernetes/Cluster.hs | 4 +- .../Sandwich/Contexts/Kubernetes/Images.hs | 15 ++++--- .../Contexts/Kubernetes/KataContainers.hs | 44 ++++++++++++++++--- .../Contexts/Kubernetes/KindCluster.hs | 10 ++++- .../Contexts/Kubernetes/MinikubeCluster.hs | 6 +++ .../Contexts/Kubernetes/MinioOperator.hs | 4 +- .../Contexts/Kubernetes/MinioS3Server.hs | 2 +- .../Sandwich/Contexts/Kubernetes/SeaweedFS.hs | 2 +- 8 files changed, 66 insertions(+), 21 deletions(-) diff --git a/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/Cluster.hs b/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/Cluster.hs index 1ebfb659..79b46b5e 100644 --- a/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/Cluster.hs +++ b/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/Cluster.hs @@ -5,9 +5,9 @@ {-| -This is the main module for creating and working with Kubernetes clusters. You can create clusters with either Kind or Minikube, obtaining the relevant binary from either the current PATH or from Nix. +Create Kubernetes clusters with either Kind or Minikube, obtaining the relevant binary from either the current PATH or from Nix. -The module also contains functions for waiting for pods and services to exist, running commands with Kubectl, logging, service forwarding, and port forwarding. +Also contains functions for waiting for pods and services to exist, running commands with Kubectl, logging, service forwarding, and port forwarding. -} diff --git a/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/Images.hs b/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/Images.hs index 221a51f4..ef278d54 100644 --- a/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/Images.hs +++ b/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/Images.hs @@ -5,7 +5,7 @@ {-| -This module contains tools for managing images on a Kubernetes cluster. +Functions for managing images on a Kubernetes cluster. -} @@ -21,12 +21,13 @@ module Test.Sandwich.Contexts.Kubernetes.Images ( , clusterContainsImage' -- * Load images - , loadImageIfNecessary - , loadImageIfNecessary' - , loadImage , loadImage' + -- * Load images if not present + , loadImageIfNecessary + , loadImageIfNecessary' + -- * Retry helpers , withImageLoadRetry , withImageLoadRetry' @@ -97,7 +98,7 @@ clusterContainsImage image = do kcc <- getContext kubernetesCluster clusterContainsImage' kcc image --- | Same as 'clusterContainsImage', but allows you to pass in the 'KubernetesClusterContext', rather than requiring one in context. +-- | Same as 'clusterContainsImage', but allows you to pass in the 'KubernetesClusterContext'. clusterContainsImage' :: ( HasCallStack, MonadUnliftIO m, MonadLogger m ) @@ -124,7 +125,7 @@ loadImageIfNecessary image = do kcc <- getContext kubernetesCluster loadImageIfNecessary' kcc image --- | Same as 'loadImage', but allows you to pass in the 'KubernetesClusterContext', rather than requiring one in context. +-- | Same as 'loadImage', but allows you to pass in the 'KubernetesClusterContext'. loadImageIfNecessary' :: ( HasCallStack, MonadFail m, KubernetesBasic context m ) @@ -200,7 +201,7 @@ withImageLoadRetry' policy ils action = action --- | Helper to introduce a list of images into a Kubernetes cluster. +-- | Introduce a list of images into a Kubernetes cluster. -- Stores the list of transformed image names under the "kubernetesClusterImages" label. introduceImages :: ( HasCallStack, KubernetesClusterBasicWithoutReader context m diff --git a/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/KataContainers.hs b/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/KataContainers.hs index 5a565d58..6a16f543 100644 --- a/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/KataContainers.hs +++ b/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/KataContainers.hs @@ -7,11 +7,21 @@ {-# OPTIONS_GHC -fno-warn-missing-signatures #-} {-# OPTIONS_GHC -fno-warn-incomplete-uni-patterns #-} +{-| + +Install [Kata Containers](https://katacontainers.io) on a Kubernetes cluster. + +-} + module Test.Sandwich.Contexts.Kubernetes.KataContainers ( + -- * Introduce Kata Containers introduceKataContainers + + -- * Bracket-style versions , withKataContainers , withKataContainers' + -- * Types , KataContainersOptions(..) , defaultKataContainersOptions @@ -72,7 +82,7 @@ data KataContainersOptions = KataContainersOptions { defaultKataContainersOptions :: KataContainersOptions defaultKataContainersOptions = KataContainersOptions { kataContainersSourceCheckout = SourceCheckoutNixDerivation kataContainersDerivation - , kataContainersKataDeployImage = Just "quay.io/kata-containers/kata-deploy:3.7.0" + , kataContainersKataDeployImage = Just "quay.io/kata-containers/kata-deploy:3.9.0" , kataContainersPreloadImages = True , kataContainersLabelNode = True } @@ -81,24 +91,46 @@ kataContainers :: Label "kataContainers" KataContainersContext kataContainers = Label type HasKataContainersContext context = HasLabel context "kataContainers" KataContainersContext +type ContextWithKataContainers context = + LabelValue "kataContainers" KataContainersContext + :> LabelValue "file-kubectl" (EnvironmentFile "kubectl") + :> context + +-- | Install Kata Containers on the cluster and introduce a 'KataContainersContext'. introduceKataContainers :: ( MonadUnliftIO m, MonadMask m, Typeable context, HasBaseContext context, HasKubernetesClusterContext context, HasNixContext context - ) => KataContainersOptions -> SpecFree (LabelValue "kataContainers" KataContainersContext :> LabelValue "file-kubectl" (EnvironmentFile "kubectl") :> context) m () -> SpecFree context m () + ) + -- | Options + => KataContainersOptions + -> SpecFree (ContextWithKataContainers context) m () + -> SpecFree context m () introduceKataContainers options = introduceBinaryViaNixPackage @"kubectl" "kubectl" . introduceWith "introduce KataContainers" kataContainers (void . withKataContainers options) +-- | Bracket-style version of 'introduceKataContainers'. withKataContainers :: forall context m a. ( HasCallStack, MonadFail m, MonadMask m, MonadLoggerIO m, MonadUnliftIO m, Typeable context , HasBaseContextMonad context m, HasKubernetesClusterContext context, HasFile context "kubectl" - ) => KataContainersOptions -> (KataContainersContext -> m a) -> m a + ) + -- | Options + => KataContainersOptions + -> (KataContainersContext -> m a) + -> m a withKataContainers options action = do kcc <- getContext kubernetesCluster kubectlBinary <- askFile @"kubectl" withKataContainers' kcc kubectlBinary options action +-- | Same as 'withKataContainers', but allows you to pass in the 'KubernetesClusterContext' and @kubectl@ binary path. withKataContainers' :: forall context m a. ( HasCallStack, MonadFail m, MonadMask m, MonadLoggerIO m, MonadUnliftIO m, Typeable context , HasBaseContextMonad context m - ) => KubernetesClusterContext -> FilePath -> KataContainersOptions -> (KataContainersContext -> m a) -> m a + ) + => KubernetesClusterContext + -- | Path to @kubectl@ binary + -> FilePath + -> KataContainersOptions + -> (KataContainersContext -> m a) + -> m a withKataContainers' kcc@(KubernetesClusterContext {..}) kubectlBinary options@(KataContainersOptions {..}) action = do -- Preflight checks case kubernetesClusterType of @@ -194,8 +226,8 @@ kataContainersDerivation = [__i|{fetchFromGitHub}: fetchFromGitHub { owner = "kata-containers"; repo = "kata-containers"; - rev = "44b08b84b00d453b6e8a96d362c3f191c4b8257e"; - sha256 = "sha256-c8C3UdQ4PZF4gxN1ZskN30OJ64IY2/N5eAkUhtUHM7E="; + rev = "cdaaf708a18da8e5f7e2b9824fa3e43b524893a5"; + sha256 = "sha256-aBcu59LybgZ9xkCDUzZXb60FeClQNG1ivfC6lWQdlb0="; } |] diff --git a/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/KindCluster.hs b/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/KindCluster.hs index e5b74e85..7a658552 100644 --- a/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/KindCluster.hs +++ b/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/KindCluster.hs @@ -1,9 +1,15 @@ -{-# LANGUAGE GADTs #-} -{-# LANGUAGE DataKinds #-} {-# LANGUAGE ConstraintKinds #-} +{-# LANGUAGE DataKinds #-} +{-# LANGUAGE GADTs #-} {-# LANGUAGE TypeApplications #-} {-# LANGUAGE TypeOperators #-} +{-| + +Create and manage Kubernetes clusters via [kind](https://kind.sigs.k8s.io/). + +-} + module Test.Sandwich.Contexts.Kubernetes.KindCluster ( introduceKindClusterViaNix , introduceKindClusterViaEnvironment diff --git a/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/MinikubeCluster.hs b/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/MinikubeCluster.hs index c489191b..72f5e4ec 100644 --- a/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/MinikubeCluster.hs +++ b/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/MinikubeCluster.hs @@ -4,6 +4,12 @@ {-# LANGUAGE TypeApplications #-} {-# LANGUAGE TypeOperators #-} +{-| + +Create and manage Kubernetes clusters via [Minikube](https://minikube.sigs.k8s.io). + +-} + module Test.Sandwich.Contexts.Kubernetes.MinikubeCluster ( -- * Introducing a cluster via Minikube introduceMinikubeClusterViaNix diff --git a/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/MinioOperator.hs b/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/MinioOperator.hs index 52fd29d9..a10d6377 100644 --- a/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/MinioOperator.hs +++ b/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/MinioOperator.hs @@ -6,9 +6,9 @@ {-| -This module can be used to install the [MinIO Kubernetes operator](https://min.io/docs/minio/kubernetes/upstream/operations/installation.html) onto a Kubernetes cluster. +Install the [MinIO Kubernetes operator](https://min.io/docs/minio/kubernetes/upstream/operations/installation.html) onto a Kubernetes cluster. -This is necessary if you want to use 'Test.Sandwich.Contexts.Kubernetes.MinioS3Server' to create actual S3 servers. +This is necessary if you want to use the 'Test.Sandwich.Contexts.Kubernetes.MinioS3Server' module to create actual S3 servers. -} diff --git a/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/MinioS3Server.hs b/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/MinioS3Server.hs index ab1adc60..27dbb8cb 100644 --- a/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/MinioS3Server.hs +++ b/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/MinioS3Server.hs @@ -4,7 +4,7 @@ {-| -This module can be used to install MinIO S3 servers onto a Kubernetes cluster. +Install MinIO S3 servers onto a Kubernetes cluster. Such a server is provided as a generic 'TestS3Server', so that you can easily run the same tests against both Kubernetes environments and normal ones. See for example the @sandwich-contexts-minio@ package. diff --git a/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/SeaweedFS.hs b/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/SeaweedFS.hs index a1c8b46c..b614560b 100644 --- a/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/SeaweedFS.hs +++ b/sandwich-contexts-kubernetes/lib/Test/Sandwich/Contexts/Kubernetes/SeaweedFS.hs @@ -9,7 +9,7 @@ {-| -This module can be used to install [SeaweedFS](https://github.com/seaweedfs/seaweedfs) deployments on a Kubernetes cluster. +Install [SeaweedFS](https://github.com/seaweedfs/seaweedfs) deployments on a Kubernetes cluster. -}