Version provider interface

config/external.go

@@ -29,6 +29,10 @@ import (
 // whatever programming language you wish, while still remaining compatible
 // with garm.
 type External struct {
+	// InterfaceVersion is the version of the interface that the external
+	// provider implements. This is used to ensure compatibility between
+	// the external provider and garm.
+	InterfaceVersion string `toml:"interface_version" json:"interface-version"`
 	// ConfigFile is the path on disk to a file which will be passed to
 	// the external binary as an environment variable: GARM_PROVIDER_CONFIG
 	// You can use this file for any configuration you need to do for the

runner/common/params.go

@@ -0,0 +1,83 @@
+// Copyright 2022 Cloudbase Solutions SRL
+//
+//    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 common
+
+import "github.com/cloudbase/garm/params"
+
+// Each struct is a wrapper for the actual parameters struct for a specific version.
+// Version 0.1.0 doesn't have any specific parameters, so there is no need for a struct for it.
+type CreateInstanceParams struct {
+	CreateInstanceV011 CreateInstanceV011Params
+}
+
+type DeleteInstanceParams struct {
+	DeleteInstanceV011 DeleteInstanceV011Params
+}
+
+type GetInstanceParams struct {
+	GetInstanceV011 GetInstanceV011Params
+}
+
+type ListInstancesParams struct {
+	ListInstancesV011 ListInstancesV011Params
+}
+
+type RemoveAllInstancesParams struct {
+	RemoveAllInstancesV011 RemoveAllInstancesV011Params
+}
+
+type StopParams struct {
+	StopV011 StopV011Params
+}
+
+type StartParams struct {
+	StartV011 StartV011Params
+}
+
+// Structs for version v0.1.1.
+type CreateInstanceV011Params struct {
+	PoolInfo       params.Pool
+	ControllerInfo params.ControllerInfo
+}
+
+type DeleteInstanceV011Params struct {
+	PoolInfo       params.Pool
+	ControllerInfo params.ControllerInfo
+}
+
+type GetInstanceV011Params struct {
+	PoolInfo       params.Pool
+	ControllerInfo params.ControllerInfo
+}
+
+type ListInstancesV011Params struct {
+	PoolInfo       params.Pool
+	ControllerInfo params.ControllerInfo
+}
+
+type RemoveAllInstancesV011Params struct {
+	PoolInfo       params.Pool
+	ControllerInfo params.ControllerInfo
+}
+
+type StopV011Params struct {
+	PoolInfo       params.Pool
+	ControllerInfo params.ControllerInfo
+}
+
+type StartV011Params struct {
+	PoolInfo       params.Pool
+	ControllerInfo params.ControllerInfo
+}

runner/common/provider.go

@@ -24,19 +24,19 @@ import (
 //go:generate mockery --all
 type Provider interface {
 	// CreateInstance creates a new compute instance in the provider.
-	CreateInstance(ctx context.Context, bootstrapParams commonParams.BootstrapInstance) (commonParams.ProviderInstance, error)
+	CreateInstance(ctx context.Context, bootstrapParams commonParams.BootstrapInstance, createInstanceParams CreateInstanceParams) (commonParams.ProviderInstance, error)
 	// Delete instance will delete the instance in a provider.
-	DeleteInstance(ctx context.Context, instance string) error
+	DeleteInstance(ctx context.Context, instance string, deleteInstanceParams DeleteInstanceParams) error
 	// GetInstance will return details about one instance.
-	GetInstance(ctx context.Context, instance string) (commonParams.ProviderInstance, error)
+	GetInstance(ctx context.Context, instance string, getInstanceParams GetInstanceParams) (commonParams.ProviderInstance, error)
 	// ListInstances will list all instances for a provider.
-	ListInstances(ctx context.Context, poolID string) ([]commonParams.ProviderInstance, error)
+	ListInstances(ctx context.Context, poolID string, listInstancesParams ListInstancesParams) ([]commonParams.ProviderInstance, error)
 	// RemoveAllInstances will remove all instances created by this provider.
-	RemoveAllInstances(ctx context.Context) error
+	RemoveAllInstances(ctx context.Context, removeAllInstancesParams RemoveAllInstancesParams) error
 	// Stop shuts down the instance.
-	Stop(ctx context.Context, instance string) error
+	Stop(ctx context.Context, instance string, stopParams StopParams) error
 	// Start boots up an instance.
-	Start(ctx context.Context, instance string) error
+	Start(ctx context.Context, instance string, startParams StartParams) error
 	// DisableJITConfig tells us if the provider explicitly disables JIT configuration and
 	// forces runner registration tokens to be used. This may happen if a provider has not yet
 	// been updated to support JIT configuration.

runner/pool/pool.go

@@ -588,7 +588,13 @@ func (r *basePoolManager) cleanupOrphanedGithubRunners(runners []*github.Runner)
 			slog.DebugContext(
 				r.ctx, "updating instances cache for pool",
 				"pool_id", pool.ID)
-			poolInstances, err = provider.ListInstances(r.ctx, pool.ID)
+			listInstancesParams := common.ListInstancesParams{
+				ListInstancesV011: common.ListInstancesV011Params{
+					PoolInfo:       pool,
+					ControllerInfo: r.controllerInfo,
+				},
+			}
+			poolInstances, err = provider.ListInstances(r.ctx, pool.ID, listInstancesParams)
 			if err != nil {
 				return errors.Wrapf(err, "fetching instances for pool %s", pool.ID)
 			}
@@ -653,7 +659,13 @@ func (r *basePoolManager) cleanupOrphanedGithubRunners(runners []*github.Runner)
 				r.ctx, "instance was found in stopped state; starting",
 				"runner_name", dbInstance.Name)
 
-			if err := provider.Start(r.ctx, dbInstance.ProviderID); err != nil {
+			startParams := common.StartParams{
+				StartV011: common.StartV011Params{
+					PoolInfo:       pool,
+					ControllerInfo: r.controllerInfo,
+				},
+			}
+			if err := provider.Start(r.ctx, dbInstance.ProviderID, startParams); err != nil {
 				return errors.Wrapf(err, "starting instance %s", dbInstance.ProviderID)
 			}
 			return nil
@@ -869,7 +881,13 @@ func (r *basePoolManager) addInstanceToProvider(instance params.Instance) error
 
 	defer func() {
 		if instanceIDToDelete != "" {
-			if err := provider.DeleteInstance(r.ctx, instanceIDToDelete); err != nil {
+			deleteInstanceParams := common.DeleteInstanceParams{
+				DeleteInstanceV011: common.DeleteInstanceV011Params{
+					PoolInfo:       pool,
+					ControllerInfo: r.controllerInfo,
+				},
+			}
+			if err := provider.DeleteInstance(r.ctx, instanceIDToDelete, deleteInstanceParams); err != nil {
 				if !errors.Is(err, runnerErrors.ErrNotFound) {
 					slog.With(slog.Any("error", err)).ErrorContext(
 						r.ctx, "failed to cleanup instance",
@@ -879,7 +897,13 @@ func (r *basePoolManager) addInstanceToProvider(instance params.Instance) error
 		}
 	}()
 
-	providerInstance, err := provider.CreateInstance(r.ctx, bootstrapArgs)
+	createInstanceParams := common.CreateInstanceParams{
+		CreateInstanceV011: common.CreateInstanceV011Params{
+			PoolInfo:       pool,
+			ControllerInfo: r.controllerInfo,
+		},
+	}
+	providerInstance, err := provider.CreateInstance(r.ctx, bootstrapArgs, createInstanceParams)
 	if err != nil {
 		instanceIDToDelete = instance.Name
 		return errors.Wrap(err, "creating instance")
@@ -1315,7 +1339,13 @@ func (r *basePoolManager) deleteInstanceFromProvider(ctx context.Context, instan
 		"runner_name", instance.Name,
 		"provider_id", identifier)
 
-	if err := provider.DeleteInstance(ctx, identifier); err != nil {
+	deleteInstanceParams := common.DeleteInstanceParams{
+		DeleteInstanceV011: common.DeleteInstanceV011Params{
+			PoolInfo:       pool,
+			ControllerInfo: r.controllerInfo,
+		},
+	}
+	if err := provider.DeleteInstance(ctx, identifier, deleteInstanceParams); err != nil {
 		return errors.Wrap(err, "removing instance")
 	}