refactor(ibmcloud): construct PULUMI_BACKEND_URL and support HTTPS COS URLs

Rename isS3Path/manageCOSRemoteState/parseS3BackedURL to
isCOSBackend/initCOSBackend/parseCOSBackedURL. Construct
PULUMI_BACKEND_URL with endpoint query params so Pulumi can connect to
COS without manual env var setup. Support both s3://bucket and HTTPS
COS endpoint URLs as --backed-url. Document COS env vars, S3 backend
usage, and --keep-state flag.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: deekay2310

docs/ibmcloud/ibm-power.md

@@ -24,6 +24,9 @@ On first boot, cloud-init automatically configures the PowerVS instance for on-p
 | `IBMCLOUD_ACCOUNT` | yes | IBM Cloud account ID |
 | `IBMCLOUD_API_KEY` | yes | IBM Cloud API key |
 | `IC_REGION` | yes | IBM Cloud region (e.g. `us-south`, `us-east`) |
+| `IBMCLOUD_COS_ACCESS_KEY_ID` | only with S3 `--backed-url` | HMAC access key for IBM Cloud Object Storage |
+| `IBMCLOUD_COS_SECRET_ACCESS_KEY` | only with S3 `--backed-url` | HMAC secret key for IBM Cloud Object Storage |
+| `IBMCLOUD_COS_ENDPOINT` | no | COS S3 endpoint (defaults to `s3.<region>.cloud-object-storage.appdomain.cloud`) |
 
 ## Create
 
@@ -134,6 +137,34 @@ podman run -d --name ibm-power \
             --otel-auth-token <uuid-token>
 ```
 
+## Using IBM Cloud Object Storage as S3 backend
+
+To store Pulumi state in IBM COS instead of a local file, create [HMAC credentials](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-uhc-hmac-credentials-main) for your COS instance and pass an `s3://` backed URL:
+
+```bash
+podman run -d --name ibm-power \
+        -v ${PWD}:/workspace:z \
+        -e IBMCLOUD_API_KEY=XXX \
+        -e IBMCLOUD_ACCOUNT=XXX \
+        -e IC_REGION=us-south \
+        -e IBMCLOUD_COS_ACCESS_KEY_ID=XXX \
+        -e IBMCLOUD_COS_SECRET_ACCESS_KEY=XXX \
+        quay.io/redhat-developer/mapt:v0.8.0 ibmcloud ibm-power create \
+            --project-name ibm-power \
+            --backed-url s3://my-cos-bucket \
+            --conn-details-output /workspace \
+            --workspace-id <workspace-id> \
+            --pi-private-subnet-id <private-subnet-id>
+```
+
+An HTTPS endpoint URL is also supported as `--backed-url`, with the bucket name in the path:
+
+```
+--backed-url https://s3.us-south.cloud-object-storage.appdomain.cloud/my-cos-bucket
+```
+
+The COS endpoint and `PULUMI_BACKEND_URL` are constructed automatically from the region and bucket name.
+
 ## Destroy
 
 ```bash
@@ -144,4 +175,20 @@ podman run -d --name ibm-power \
         quay.io/redhat-developer/mapt:v0.8.0 ibmcloud ibm-power destroy \
             --project-name ibm-power \
             --backed-url file:///workspace
+```
+
+By default, destroy removes the Pulumi state files from the backend after a successful destroy. Use `--keep-state` to preserve them:
+
+```bash
+podman run -d --name ibm-power \
+        -v ${PWD}:/workspace:z \
+        -e IBMCLOUD_API_KEY=XXX \
+        -e IBMCLOUD_ACCOUNT=XXX \
+        -e IC_REGION=us-south \
+        -e IBMCLOUD_COS_ACCESS_KEY_ID=XXX \
+        -e IBMCLOUD_COS_SECRET_ACCESS_KEY=XXX \
+        quay.io/redhat-developer/mapt:v0.8.0 ibmcloud ibm-power destroy \
+            --project-name ibm-power \
+            --backed-url s3://my-cos-bucket \
+            --keep-state
 ```

docs/ibmcloud/ibm-z.md

@@ -15,6 +15,9 @@ Two networking modes are supported:
 | `IBMCLOUD_API_KEY` | yes | IBM Cloud API key |
 | `IC_REGION` | yes | IBM Cloud region (e.g. `us-south`, `us-east`) |
 | `IC_ZONE` | only without `--subnet-id` | Availability zone (e.g. `us-south-2`) |
+| `IBMCLOUD_COS_ACCESS_KEY_ID` | only with S3 `--backed-url` | HMAC access key for IBM Cloud Object Storage |
+| `IBMCLOUD_COS_SECRET_ACCESS_KEY` | only with S3 `--backed-url` | HMAC secret key for IBM Cloud Object Storage |
+| `IBMCLOUD_COS_ENDPOINT` | no | COS S3 endpoint (defaults to `s3.<region>.cloud-object-storage.appdomain.cloud`) |
 
 ## Create
 
@@ -112,6 +115,33 @@ podman run -d --name ibm-z \
             --otel-auth-token <uuid-token>
 ```
 
+## Using IBM Cloud Object Storage as S3 backend
+
+To store Pulumi state in IBM COS instead of a local file, create [HMAC credentials](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-uhc-hmac-credentials-main) for your COS instance and pass an `s3://` backed URL:
+
+```bash
+podman run -d --name ibm-z \
+        -v ${PWD}:/workspace:z \
+        -e IBMCLOUD_API_KEY=XXX \
+        -e IBMCLOUD_ACCOUNT=XXX \
+        -e IC_REGION=us-south \
+        -e IC_ZONE=us-south-2 \
+        -e IBMCLOUD_COS_ACCESS_KEY_ID=XXX \
+        -e IBMCLOUD_COS_SECRET_ACCESS_KEY=XXX \
+        quay.io/redhat-developer/mapt:v0.8.0 ibmcloud ibm-z create \
+            --project-name ibm-z \
+            --backed-url s3://my-cos-bucket \
+            --conn-details-output /workspace
+```
+
+An HTTPS endpoint URL is also supported as `--backed-url`, with the bucket name in the path:
+
+```
+--backed-url https://s3.us-south.cloud-object-storage.appdomain.cloud/my-cos-bucket
+```
+
+The COS endpoint and `PULUMI_BACKEND_URL` are constructed automatically from the region and bucket name.
+
 ## Destroy
 
 ```bash
@@ -123,3 +153,19 @@ podman run -d --name ibm-z \
             --project-name ibm-z \
             --backed-url file:///workspace
 ```
+
+By default, destroy removes the Pulumi state files from the backend after a successful destroy. Use `--keep-state` to preserve them:
+
+```bash
+podman run -d --name ibm-z \
+        -v ${PWD}:/workspace:z \
+        -e IBMCLOUD_API_KEY=XXX \
+        -e IBMCLOUD_ACCOUNT=XXX \
+        -e IC_REGION=us-south \
+        -e IBMCLOUD_COS_ACCESS_KEY_ID=XXX \
+        -e IBMCLOUD_COS_SECRET_ACCESS_KEY=XXX \
+        quay.io/redhat-developer/mapt:v0.8.0 ibmcloud ibm-z destroy \
+            --project-name ibm-z \
+            --backed-url s3://my-cos-bucket \
+            --keep-state
+```

pkg/provider/ibmcloud/ibmcloud.go

@@ -23,8 +23,8 @@ const (
 type IBMCloud struct{}
 
 func (i *IBMCloud) Init(ctx context.Context, backedURL string) error {
-	if isS3Path(backedURL) {
-		return manageCOSRemoteState(backedURL)
+	if isCOSBackend(backedURL) {
+		return initCOSBackend(backedURL)
 	}
 	return nil
 }
@@ -59,8 +59,11 @@ var (
 	DefaultCredentials = GetClouProviderCredentials(nil)
 )
 
-func isS3Path(backedURL string) bool {
-	return strings.HasPrefix(backedURL, "s3://")
+const cosHostSuffix = "cloud-object-storage.appdomain.cloud"
+
+func isCOSBackend(backedURL string) bool {
+	return strings.HasPrefix(backedURL, "s3://") ||
+		strings.Contains(backedURL, cosHostSuffix)
 }
 
 func ensureHTTPS(endpoint string) string {
@@ -82,7 +85,25 @@ func requireEnv(name string) (string, error) {
 	return v, nil
 }
 
-func manageCOSRemoteState(backedURL string) error {
+func extractBucket(backedURL string) (string, error) {
+	u, err := url.Parse(backedURL)
+	if err != nil {
+		return "", fmt.Errorf("failed to parse backed URL %q: %w", backedURL, err)
+	}
+	if strings.HasPrefix(backedURL, "s3://") {
+		if u.Host == "" {
+			return "", fmt.Errorf("backed URL %q missing bucket name (expected s3://bucket-name)", backedURL)
+		}
+		return u.Host, nil
+	}
+	bucket := strings.TrimPrefix(u.Path, "/")
+	if bucket == "" {
+		return "", fmt.Errorf("backed URL %q missing bucket name in path (expected https://<endpoint>/<bucket>)", backedURL)
+	}
+	return strings.SplitN(bucket, "/", 2)[0], nil
+}
+
+func initCOSBackend(backedURL string) error {
 	accessKey, err := requireEnv(icConstants.EnvIBMCosAccessKeyID)
 	if err != nil {
 		return err
@@ -101,32 +122,46 @@ func manageCOSRemoteState(backedURL string) error {
 		endpoint = fmt.Sprintf("s3.%s.cloud-object-storage.appdomain.cloud", region)
 	}
 
+	bucket, err := extractBucket(backedURL)
+	if err != nil {
+		return err
+	}
+
+	pulumiBackendURL := fmt.Sprintf("s3://%s?endpoint=%s&s3ForcePathStyle=true",
+		bucket, ensureHTTPS(endpoint))
+
 	for k, v := range map[string]string{
 		"AWS_ACCESS_KEY_ID":     accessKey,
 		"AWS_SECRET_ACCESS_KEY": secretKey,
 		"AWS_ENDPOINT_URL":      ensureHTTPS(endpoint),
 		"AWS_REGION":            region,
 		"AWS_DEFAULT_REGION":    region,
 		"AWS_S3_USE_PATH_STYLE": "true",
+		"PULUMI_BACKEND_URL":    pulumiBackendURL,
 	} {
 		if err := os.Setenv(k, v); err != nil {
 			return err
 		}
 	}
+	logging.Debugf("COS backend configured: %s", pulumiBackendURL)
 	return nil
 }
 
-func parseS3BackedURL(mCtx *mc.Context) (*string, *string, error) {
-	if !strings.HasPrefix(mCtx.BackedURL(), "s3://") {
-		return nil, nil, fmt.Errorf("invalid S3 URI: must start with s3://")
+func parseCOSBackedURL(mCtx *mc.Context) (*string, *string, error) {
+	backendURL := os.Getenv("PULUMI_BACKEND_URL")
+	if backendURL == "" {
+		backendURL = mCtx.BackedURL()
+	}
+	if !strings.HasPrefix(backendURL, "s3://") {
+		return nil, nil, fmt.Errorf("invalid S3 URI %q: must start with s3://", backendURL)
 	}
-	u, err := url.Parse(mCtx.BackedURL())
+	u, err := url.Parse(backendURL)
 	if err != nil {
 		return nil, nil, fmt.Errorf("failed to parse S3 URI: %w", err)
 	}
 	key := strings.TrimPrefix(u.Path, "/")
 	if key == "" {
-		return nil, nil, fmt.Errorf("invalid S3 URI %q: missing object key after bucket name", mCtx.BackedURL())
+		return nil, nil, fmt.Errorf("invalid S3 URI %q: missing object key after bucket name", backendURL)
 	}
 	return &u.Host, &key, nil
 }
@@ -137,7 +172,7 @@ func DestroyStack(mCtx *mc.Context, stackName string) error {
 		return fmt.Errorf("stackname is required")
 	}
 	if mCtx.IsForceDestroy() {
-		bucket, key, err := parseS3BackedURL(mCtx)
+		bucket, key, err := parseCOSBackedURL(mCtx)
 		if err != nil {
 			logging.Error(err)
 		} else {
@@ -161,7 +196,7 @@ func CleanupState(mCtx *mc.Context) error {
 		return nil
 	}
 
-	bucket, key, parseErr := parseS3BackedURL(mCtx)
+	bucket, key, parseErr := parseCOSBackedURL(mCtx)
 	if parseErr != nil {
 		logging.Warnf("Failed to parse S3 backend URL, skipping state cleanup: %v", parseErr)
 		return nil