sandwich-contexts-kubernetes: more haddocks

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.
 
 -}
 

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

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=";
                                 }
                                |]
 

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

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

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.
 
 -}
 

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.
 

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.
 
 -}