feat: first draft of Infrastructure API and related models

build-logic/project-plugins/src/main/kotlin/com.hedera.fullstack.jpms-modules.gradle.kts

@@ -24,6 +24,7 @@ plugins {
 javaModuleDependencies {
     moduleNameToGA.put("com.hedera.fullstack.junit.support", "com.hedera.fullstack:fullstack-junit-support")
     moduleNameToGA.put("com.hedera.fullstack.test.toolkit", "com.hedera.fullstack:fullstack-test-toolkit")
+    moduleNameToGA.put("com.hedera.fullstack.base.api", "com.hedera.fullstack:fullstack-base-api")
     moduleNameToGA.put("com.hedera.fullstack.readiness.api", "com.hedera.fullstack:fullstack-readiness-api")
     moduleNameToGA.put("com.hedera.fullstack.monitoring.api", "com.hedera.fullstack:fullstack-monitoring-api")
     moduleNameToGA.put("com.hedera.fullstack.validator.api", "com.hedera.fullstack:fullstack-validator-api")

fullstack-core/fullstack-configuration-api/src/main/java/com/hedera/fullstack/configuration/infrastructure/InstallType.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright (C) 2023 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.hedera.fullstack.configuration.infrastructure;
+
+/**
+ * Defines the type of installation of a node
+ */
+public enum InstallType {
+    /**
+     * The node is installed using Node Management Tool (NMT) and uses a released artifact
+     */
+    NMT,
+    /**
+     * The node is installed by directly copying the build artifact to the node without the use of NMT.
+     * Though the build artifact can be a both a released artifact or a built locally on a development machine,
+     * this is typically used by developers for adhoc build testing.
+     */
+    DIRECT_INSTALL
+}

fullstack-core/fullstack-configuration-api/src/main/java/com/hedera/fullstack/configuration/infrastructure/NetworkDeploymentConfiguration.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright (C) 2023 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.hedera.fullstack.configuration.infrastructure;
+
+import java.util.List;
+
+/**
+ * A container class to hold all configuration needed to hold the NetworkDeployment
+ */
+public class NetworkDeploymentConfiguration {
+
+    // FUTURE: This class needs to closely reflect what will be passed in values.yaml
+
+    InstallType installType;
+    List<Node> nodes;
+}

fullstack-core/fullstack-configuration-api/src/main/java/com/hedera/fullstack/configuration/infrastructure/Node.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright (C) 2023 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.hedera.fullstack.configuration.infrastructure;
+
+/**
+ * Describes configuration of a Node component inside the NetworkNode Workload
+ * @param ram - The amount of ram in GB needed for the node
+ * @param cpu - The amount of cpu in cores needed for the node
+ * @param nodeID - The nodeID of the node
+ * @param nodeAccountID - The nodeAccountID of the node
+ */
+public record Node(int ram, int cpu, int nodeID, int nodeAccountID) {}

fullstack-core/fullstack-configuration-api/src/main/java/module-info.java

@@ -1 +1,3 @@
-module com.hedera.fullstack.configuration.api {}
+module com.hedera.fullstack.configuration.api {
+    exports com.hedera.fullstack.configuration.infrastructure;
+}

fullstack-core/fullstack-infrastructure-api/build.gradle.kts

@@ -22,5 +22,6 @@ plugins {
 
 dependencies {
     api(platform(project(":fullstack-bom")))
-    implementation(project(mapOf("path" to ":fullstack-helm-client")))
+    implementation(project(":fullstack-helm-client"))
+    implementation(project(":fullstack-configuration-api"))
 }

fullstack-core/fullstack-infrastructure-api/src/main/java/com/hedera/fullstack/infrastructure/api/exceptions/InfrastructureException.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright (C) 2023 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.hedera.fullstack.infrastructure.api.exceptions;
+
+/**
+ *
+ * <p>Thrown when an infrastructure-related exception occurs at the lower level of the implementation.</p>
+ * <p>A nested exception (cause) should be provided to capture the root cause of the exception.</p>
+ * <p>This is not necessarily a fatal exception and the network deployment may be able to recover from it depending on the cause.</p>
+ *
+ */
+public class InfrastructureException extends Exception {
+    InfrastructureException(String message) {
+        super(message);
+    }
+
+    InfrastructureException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

fullstack-core/fullstack-infrastructure-api/src/main/java/com/hedera/fullstack/infrastructure/api/exceptions/InstallationException.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright (C) 2023 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.hedera.fullstack.infrastructure.api.exceptions;
+
+/**
+ * <p>Thrown if an exceptions happens during fullstack "cluster setup".
+ * The "cluster setup" installs prerequisites on a cluster before a {@link com.hedera.fullstack.infrastructure.api.model.NetworkDeployment} can be deployed.
+ * </p>
+ *
+ * <p>A nested exception is provided to give more details about the cause of the exception.</p>
+ */
+public class InstallationException extends Exception {
+    public InstallationException(String message) {
+        super(message);
+    }
+
+    public InstallationException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

fullstack-core/fullstack-infrastructure-api/src/main/java/com/hedera/fullstack/infrastructure/api/exceptions/InsufficientClusterResourcesException.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright (C) 2023 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.hedera.fullstack.infrastructure.api.exceptions;
+
+/**
+ * Thrown when there are not enough resources on the cluster to deploy a new node.
+ * This can be remedied by adding more resources to the cluster or deleting existing deployments on the cluster
+ */
+public class InsufficientClusterResourcesException extends Exception {
+    public InsufficientClusterResourcesException(String message) {
+        super(message);
+    }
+}

fullstack-core/fullstack-infrastructure-api/src/main/java/com/hedera/fullstack/infrastructure/api/exceptions/InvalidConfigurationException.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright (C) 2023 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.hedera.fullstack.infrastructure.api.exceptions;
+
+/**
+ * <p>Thrown when the {@link com.hedera.fullstack.configuration.infrastructure.NetworkDeploymentConfiguration} is invalid.</p>
+ * <p>This can happen if the network deployment configuration has failed validation even before the deployment has started.</p>
+ */
+public class InvalidConfigurationException extends Exception {
+    public InvalidConfigurationException(String message) {
+        super(message);
+    }
+}

fullstack-core/fullstack-infrastructure-api/src/main/java/com/hedera/fullstack/infrastructure/api/exceptions/NetworkDeploymentNotFoundException.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright (C) 2023 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.hedera.fullstack.infrastructure.api.exceptions;
+
+/**
+ * Thrown if a {@link com.hedera.fullstack.infrastructure.api.model.NetworkDeployment} with cannot be found
+ */
+public class NetworkDeploymentNotFoundException extends Exception {
+    NetworkDeploymentNotFoundException(String message) {
+        super(message);
+    }
+}

fullstack-core/fullstack-infrastructure-api/src/main/java/com/hedera/fullstack/infrastructure/api/manager/InfrastructureManager.java

@@ -0,0 +1,97 @@
+/*
+ * Copyright (C) 2023 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.hedera.fullstack.infrastructure.api.manager;
+
+import com.hedera.fullstack.configuration.infrastructure.NetworkDeploymentConfiguration;
+import com.hedera.fullstack.infrastructure.api.exceptions.InsufficientClusterResourcesException;
+import com.hedera.fullstack.infrastructure.api.exceptions.InfrastructureException;
+import com.hedera.fullstack.infrastructure.api.exceptions.InvalidConfigurationException;
+import com.hedera.fullstack.infrastructure.api.exceptions.NetworkDeploymentNotFoundException;
+import com.hedera.fullstack.infrastructure.api.model.NetworkDeployment;
+import java.util.List;
+import java.util.concurrent.Future;
+
+/**
+ * <p>InfrastructureManager is the main entry point into infrastructure management for FST </p>
+ *
+ * Responsibilities:
+ * <ol>
+ *  <li> Manages the lifecycle of a {@link NetworkDeployment}</li>
+ *  <li> Acts as a registry for all {@link NetworkDeployment}s created by it</li></li>
+ * </ol>
+ *
+ * <hr/>
+ * <strong> About NetworkDeployments </strong>
+ * <p>
+ * A {@link NetworkDeployment} represents all the workloads and their components needed for a Hedera ecosystem. <br/>
+ * Upon instantiation, the {@link NetworkDeployment} object can interact with its workloads and components directly
+ * and does not need {@link InfrastructureManager}.
+ * </p>
+ */
+public interface InfrastructureManager {
+
+    /**
+     * This is a synchronous version of {@link #createNetworkDeploymentAsync(NetworkDeploymentConfiguration)}
+     * @throws InvalidConfigurationException if the {@link NetworkDeploymentConfiguration} is invalid
+     * @throws InsufficientClusterResourcesException if there are not enough resources in the cluster to create the {@link NetworkDeployment}
+     * @throws InfrastructureException if there is an infrastructure related exception during creation of the {@link NetworkDeployment}.
+     * The underlying cause will be captured in the nested exception.
+     * If a deployment has already started, it may leave behind partially created resources.
+     * These partial resources can be cleaned by {@link NetworkDeployment#delete()
+     */
+    default NetworkDeployment createNetworkDeployment(NetworkDeploymentConfiguration hederaNetwork)
+            throws InvalidConfigurationException, InsufficientClusterResourcesException, InfrastructureException {
+        return null;
+    }
+
+    /**
+     * <p>Creates the {@link NetworkDeployment} based on the {@link NetworkDeploymentConfiguration} provided.
+     * This is a long-running process.</p>
+     * <p>Note: the {@link NetworkDeployment} can be spread across multiple clusters and cloud providers.</p>
+     * <p>Since this method returns a {@code Future} any exceptions thrown during the asynchronous execution
+     * will be wrapped in a {@link java.util.concurrent.ExecutionException}
+     * </p>
+     * @param hederaNetwork {@link NetworkDeploymentConfiguration} object containing all the configuration needed
+     *                    to create the {@link NetworkDeployment}
+     * @return a {@link NetworkDeployment} object representing the {@link NetworkDeployment} created
+     * @throws InvalidConfigurationException if the {@link NetworkDeploymentConfiguration} is invalid
+     * @throws InsufficientClusterResourcesException if there are not enough resources in the cluster to create the {@link NetworkDeployment}
+     * @throws InfrastructureException if there is an infrastructure related exception, the underlying cause
+     * will be captured in the nested exception.
+     * @throws NullPointerException if the {@code hederaNetwork} configuration is {@code null}.
+     */
+    Future<NetworkDeployment> createNetworkDeploymentAsync(NetworkDeploymentConfiguration hederaNetwork)
+            throws InvalidConfigurationException, InsufficientClusterResourcesException, InfrastructureException;
+
+    /**
+     * List all the {@link NetworkDeployment} instances created by this JVM process.
+     * @return a list of all {@link NetworkDeployment}s instances provisioned by this JVM process.
+     */
+    List<NetworkDeployment> listNetworkDeployments();
+
+    /**
+     * Locates an existing {@link NetworkDeployment} using the provided identifier.
+     * The identifier must be from a {@link NetworkDeployment} created by this Java process.
+     * @param id  Unique identifier of the {@link NetworkDeployment}, the implementation
+     *           will usually be a combination of namespace, job name and job id etc.
+     * @return the {@link NetworkDeployment} associated with the provided identifier.
+     * @throws NetworkDeploymentNotFoundException if the {@link NetworkDeployment} with the given identifier is not found
+     * @throws IllegalArgumentException if the provided id is null or empty.
+     */
+    NetworkDeployment networkDeploymentById(String id) throws NetworkDeploymentNotFoundException, IllegalArgumentException;
+
+}