/// <summary>
/// <para>
/// Deploys a new test cluster as specified by the cluster definition passed or connects
/// to a cluster previously deployed by this method when the cluster definition of the
/// existing cluster and the definition passed here are the same.
/// </para>
/// </summary>
/// <param name="clusterDefinition">The cluster definition model.</param>
/// <param name="options">
/// Optionally specifies the options that <see cref="ClusterFixture"/> will use to
/// manage the test cluster.
/// </param>
/// <returns>
/// <para>
/// The <see cref="TestFixtureStatus"/>:
/// </para>
/// <list type="table">
/// <item>
/// <term><see cref="TestFixtureStatus.Disabled"/></term>
/// <description>
/// Returned when cluster unit testing is disabled due to the <c>NEON_CLUSTER_TESTING</c> environment
/// variable not being present on the current machine which means that <see cref="TestHelper.IsClusterTestingEnabled"/>
/// returns <c>false</c>.
/// </description>
/// </item>
/// <item>
/// <term><see cref="TestFixtureStatus.Started"/></term>
/// <description>
/// Returned when one of the <c>Start()</c> methods is called for the first time for the fixture
/// instance, indicating that an existing cluster has been connected or a new cluster has been deployed.
/// </description>
/// </item>
/// <item>
/// <term><see cref="TestFixtureStatus.AlreadyRunning"/></term>
/// <description>
/// Returned when one of the <c>Start()</c> methods has already been called by your test
/// class instance.
/// </description>
/// </item>
/// </list>
/// </returns>
/// <exception cref="NeonKubeException">Thrown when the test cluster could not be deployed.</exception>
/// <remarks>
/// <para>
/// <b>IMPORTANT:</b> Only one <see cref="ClusterFixture"/> can be run at a time on
/// any one computer. This is due to the fact that cluster state like the kubeconfig,
/// neonKUBE logins, logs and other files will be written to <b>~/.neonkube/spaces/$fixture/*</b>
/// so multiple fixture instances will be confused when trying to manage these same files.
/// </para>
/// <para>
/// This means that not only will running <see cref="ClusterFixture"/> based tests in parallel
/// within the same instance of Visual Studio fail, but running these tests in different
/// Visual Studio instances will also fail.
/// </para>
/// </remarks>
public TestFixtureStatus StartWithClusterDefinition(ClusterDefinition clusterDefinition, ClusterFixtureOptions options = null)
{
Covenant.Requires <ArgumentNullException>(clusterDefinition != null, nameof(clusterDefinition));
if (clusterDefinition.IsLocked)
{
throw new NeonKubeException("Test clusters need to be unlocked. Please set [isLocked: false] in your cluster definition.");
}
if (!TestHelper.IsClusterTestingEnabled)
{
return(TestFixtureStatus.Disabled);
}
if (started)
{
return(TestFixtureStatus.AlreadyRunning);
}
options ??= new ClusterFixtureOptions();
this.options = options.Clone();
if (this.Cluster != null)
{
return(TestFixtureStatus.AlreadyRunning);
}
// Set the clusterspace mode, using any previously downloaded node image unless
// the user specifies a custom image. We're going to host the fixture state
// files in this fixed folder:
//
// ~/.neonkube/spaces/$fixture/*
clusterspaceFolder = KubeHelper.SetClusterSpaceMode(string.IsNullOrEmpty(options.ImageUriOrPath) ? KubeClusterspaceMode.EnabledWithSharedCache : KubeClusterspaceMode.Enabled, KubeHelper.ClusterspacePrefix("fixture"));
// Figure out whether the user passed an image URI or file path to override
// the default node image.
var imageUriOrPath = options.ImageUriOrPath;
var imageUri = (string)null;
var imagePath = (string)null;
if (string.IsNullOrEmpty(imageUriOrPath))
{
imageUriOrPath = KubeDownloads.GetDefaultNodeImageUri(clusterDefinition.Hosting.Environment);
}
if (imageUriOrPath.StartsWith("http://", StringComparison.InvariantCultureIgnoreCase) || imageUriOrPath.StartsWith("https://", StringComparison.InvariantCultureIgnoreCase))
{
imageUri = imageUriOrPath;
}
else
{
imagePath = imageUriOrPath;
}
//-------------------------------------------------------------
// We need to deal with some scenarios here:
//
// 1. No cluster context or login exists for the target cluster.
//
// A conflicting cluster may still exist though, having been deployed
// by another computer or perhaps the kubecontext/logins on the current
// machine may have been modified. We need to be sure to remove any
// conflicting resources in this case.
//
// 2. Cluster context and login exist on the current machine for the target
// cluster but the cluster is unhealthy or locked. We'll abort for locked
// clusters and remove and redeploy for unhealth clusters.
//
// 3. Cluster context and login exist and the cluster is healthy. In this case,
// we need to compare the deployed cluster version against the current version
// and remove/redeploy when the versions don't match.
//
// 4. Cluster context and login exist and the cluster is healthy and cluster versions
// match. In this case, We'll compare the existing cluster definition with that for
// the new cluster and also compare the cluster versions and if they match and
// [RemoveClusterOnStart=false] we'll just use the existing cluster.
//
// 5. The current cluster matches the target but [RemoveClusterOnStart=true].
// We need to remove the current cluster in this case so we'll deploy a
// fresh one.
// Determine whether a test cluster with the same name exists and if
// its cluster definition matches the test cluster's definition.
;
var clusterExists = false;
var clusterContextName = KubeContextName.Parse($"root@{clusterDefinition.Name}");
var clusterContext = KubeHelper.Config.GetContext(clusterContextName);
var clusterLogin = KubeHelper.GetClusterLogin(clusterContextName);
if (clusterContext != null && clusterLogin != null && !clusterLogin.SetupDetails.SetupPending)
{
clusterExists = ClusterDefinition.AreSimilar(clusterDefinition, clusterLogin.ClusterDefinition);
}
if (clusterExists && !options.RemoveClusterOnStart)
{
// It looks like the test cluster may already exist. We'll verify
// that it's running, healthy, unlocked and the cluster versions match.
// When all of these conditions are true, we'll use the existing cluster,
// otherwise we'll remove the cluster as well as its context/login,
// and deploy a new cluster below.
using (var cluster = new ClusterProxy(clusterLogin.ClusterDefinition, new HostingManagerFactory()))
{
KubeHelper.SetCurrentContext(clusterContextName);
var isLocked = cluster.IsLockedAsync().ResultWithoutAggregate();
var clusterInfo = cluster.GetClusterInfoAsync().ResultWithoutAggregate();
var clusterHealth = cluster.GetClusterHealthAsync().ResultWithoutAggregate();
if (isLocked.HasValue && isLocked.Value)
{
throw new NeonKubeException($"Cluster is locked: {cluster.Name}");
}
if (clusterHealth.State == ClusterState.Healthy && clusterInfo.ClusterVersion == KubeVersions.NeonKube)
{
// We need to reset an existing cluster to ensure it's in a known state.
cluster.ResetAsync().WaitWithoutAggregate();
started = true;
IsRunning = true;
Cluster = new ClusterProxy(KubeHelper.CurrentContext, new HostingManagerFactory());
return(TestFixtureStatus.Started);
}
cluster.RemoveAsync(removeOrphans: true).WaitWithoutAggregate();
}
}
else
{
// There is no known existing cluster but there still might be a cluster
// deployed by another machine or fragments of a partially deployed cluster,
// so we need to do a preemptive cluster remove.
using (var cluster = new ClusterProxy(clusterDefinition, new HostingManagerFactory()))
{
cluster.RemoveAsync(removeOrphans: true).WaitWithoutAggregate();
}
}
// Provision the new cluster.
WriteTestOutputLine($"PREPARE CLUSTER: {clusterDefinition.Name}");
try
{
var controller = KubeSetup.CreateClusterPrepareController(
clusterDefinition: clusterDefinition,
nodeImageUri: imageUri,
nodeImagePath: imagePath,
maxParallel: options.MaxParallel,
unredacted: options.Unredacted,
neonCloudHeadendUri: options.NeonCloudHeadendUri);
switch (controller.RunAsync().ResultWithoutAggregate())
{
case SetupDisposition.Succeeded:
WriteTestOutputLine("CLUSTER PREPARE: SUCCESS");
break;
case SetupDisposition.Failed:
WriteTestOutputLine("CLUSTER PREPARE: FAIL");
throw new NeonKubeException("Cluster prepare failed.");
case SetupDisposition.Cancelled:
default:
throw new NotImplementedException();
}
}
finally
{
if (options.CaptureDeploymentLogs)
{
CaptureDeploymentLogs();
}
}
// Setup the cluster.
WriteTestOutputLine($"SETUP CLUSTER: {clusterDefinition.Name}");
try
{
var controller = KubeSetup.CreateClusterSetupController(
clusterDefinition: clusterDefinition,
maxParallel: options.MaxParallel,
unredacted: options.Unredacted);
switch (controller.RunAsync().ResultWithoutAggregate())
{
case SetupDisposition.Succeeded:
WriteTestOutputLine("CLUSTER SETUP: SUCCESS");
break;
case SetupDisposition.Failed:
WriteTestOutputLine("CLUSTER SETUP: FAILED");
throw new NeonKubeException("Cluster setup failed.");
case SetupDisposition.Cancelled:
default:
throw new NotImplementedException();
}
}
finally
{
if (options.CaptureDeploymentLogs)
{
CaptureDeploymentLogs();
}
}
// NOTE: We just deployed brand new cluster so there's no need to reset it.
started = true;
IsRunning = true;
Cluster = new ClusterProxy(KubeHelper.CurrentContext, new HostingManagerFactory());
return(TestFixtureStatus.Started);
}
/// <inheritdoc/>
public override async Task RunAsync(CommandLine commandLine)
{
if (commandLine.HasHelpOption)
{
Help();
Program.Exit(0);
}
Console.WriteLine();
// Cluster prepare/setup uses the [ProfileClient] to retrieve secrets and profile values.
// We need to inject an implementation for [PreprocessReader] so it will be able to
// perform the lookups.
NeonHelper.ServiceContainer.AddSingleton <IProfileClient>(new ProfileClient());
// Handle the [--remove-templates] option.
if (commandLine.HasOption("--remove-templates"))
{
Console.WriteLine("Removing cached virtual machine templates.");
foreach (var fileName in Directory.GetFiles(KubeHelper.NodeImageFolder, "*.*", SearchOption.TopDirectoryOnly))
{
File.Delete(fileName);
}
}
var nodeImageUri = commandLine.GetOption("--node-image-uri");
var nodeImagePath = commandLine.GetOption("--node-image-path");
var debug = commandLine.HasOption("--debug");
var baseImageName = commandLine.GetOption("--base-image-name");
var clusterspace = commandLine.GetOption("--clusterspace");
var headendUri = commandLine.GetOption("--headend-uri") ?? KubeConst.NeonCloudHeadendUri;
var maxParallelOption = commandLine.GetOption("--max-parallel", "6");
var disablePending = commandLine.HasOption("--disable-pending");
if (!int.TryParse(maxParallelOption, out var maxParallel) || maxParallel <= 0)
{
Console.Error.WriteLine($"*** ERROR: [--max-parallel={maxParallelOption}] is not valid.");
Program.Exit(1);
}
if (debug && string.IsNullOrEmpty(baseImageName))
{
Console.Error.WriteLine($"*** ERROR: [--base-image-name] is required for [--debug] mode.");
Program.Exit(1);
}
// Implement the command.
if (KubeHelper.CurrentContext != null)
{
Console.Error.WriteLine("*** ERROR: You are logged into a cluster. You need to logout before preparing another.");
Program.Exit(1);
}
if (commandLine.Arguments.Length == 0)
{
Console.Error.WriteLine($"*** ERROR: CLUSTER-DEF expected.");
Program.Exit(1);
}
// Obtain the cluster definition.
var clusterDefPath = commandLine.Arguments[0];
var clusterDefinition = (ClusterDefinition)null;
ClusterDefinition.ValidateFile(clusterDefPath, strict: true);
clusterDefinition = ClusterDefinition.FromFile(clusterDefPath, strict: true);
// Do a quick sanity check to ensure that the hosting environment has enough
// resources (memory and disk) to actually host the cluster.
using (var cluster = new ClusterProxy(clusterDefinition, new HostingManagerFactory()))
{
var status = await cluster.GetResourceAvailabilityAsync();
if (!status.CanBeDeployed)
{
Console.Error.WriteLine();
Console.Error.WriteLine($"*** ERROR: Insufficent resources available to deploy cluster.");
Console.Error.WriteLine();
foreach (var entity in status.Constraints.Keys
.OrderBy(key => key, StringComparer.InvariantCultureIgnoreCase))
{
Console.Error.WriteLine();
Console.Error.WriteLine($"{entity}:");
foreach (var constraint in status.Constraints[entity])
{
Console.Error.WriteLine($" {constraint.ResourceType.ToString().ToUpperInvariant()}: {constraint.Details}");
}
}
Console.Error.WriteLine();
Program.Exit(1);
}
}
if (KubeHelper.IsOnPremiseHypervisorEnvironment(clusterDefinition.Hosting.Environment))
{
// Use the default node image for the hosting environment unless [--node-image-uri]
// or [--node-image-path] was specified.
if (string.IsNullOrEmpty(nodeImageUri) && string.IsNullOrEmpty(nodeImagePath))
{
nodeImageUri = KubeDownloads.GetDefaultNodeImageUri(clusterDefinition.Hosting.Environment);
}
}
// Parse any specified package cache endpoints.
var packageCaches = commandLine.GetOption("--package-caches", null);
var packageCacheEndpoints = new List <IPEndPoint>();
if (!string.IsNullOrEmpty(packageCaches))
{
foreach (var item in packageCaches.Split(' ', StringSplitOptions.RemoveEmptyEntries))
{
if (!NetHelper.TryParseIPv4Endpoint(item, out var endpoint))
{
Console.Error.WriteLine($"*** ERROR: [{item}] is not a valid package cache IPv4 endpoint.");
Program.Exit(1);
}
packageCacheEndpoints.Add(endpoint);
}
}
// Create and run the cluster prepare controller.
var controller = KubeSetup.CreateClusterPrepareController(
clusterDefinition,
nodeImageUri: nodeImageUri,
nodeImagePath: nodeImagePath,
maxParallel: maxParallel,
packageCacheEndpoints: packageCacheEndpoints,
unredacted: commandLine.HasOption("--unredacted"),
debugMode: debug,
baseImageName: baseImageName,
clusterspace: clusterspace,
neonCloudHeadendUri: headendUri);
controller.DisablePendingTasks = disablePending;
controller.StatusChangedEvent +=
status =>
{
status.WriteToConsole();
};
switch (await controller.RunAsync())
{
case SetupDisposition.Succeeded:
var pendingGroups = controller.GetPendingGroups();
if (pendingGroups.Count > 0)
{
Console.WriteLine($"*** ERROR: [{pendingGroups.Count}] pending task groups have not been awaited:");
Console.WriteLine();
foreach (var groupName in pendingGroups)
{
Console.WriteLine($" {groupName}");
}
Program.Exit(1);
}
Console.WriteLine();
Console.WriteLine($" [{clusterDefinition.Name}] cluster is prepared.");
Console.WriteLine();
Program.Exit(0);
break;
case SetupDisposition.Cancelled:
Console.WriteLine();
Console.WriteLine(" *** CANCELLED: Cluster prepare was cancelled.");
Console.WriteLine();
Program.Exit(1);
break;
case SetupDisposition.Failed:
Console.WriteLine();
Console.WriteLine(" *** ERROR: Cluster prepare has failed. Examine the logs here:");
Console.WriteLine();
Console.WriteLine($" {KubeHelper.LogFolder}");
Console.WriteLine();
Program.Exit(1);
break;
default:
throw new NotImplementedException();
}
await Task.CompletedTask;
}
