Add support for Entra SecurityGroup (#4768)

* Scaffold bare resource

* Rename test file

* Scaffold reconciler and registration

* Add targets to tidy go.mod files

* Update securitygroup

* Create Entra client

* Updates

* Update imports

* Checkpoint

* Add annotation helpers and test

* Update resource shape

* Test updates too

* Fix status after update

* Add recording for test

* Export EntraID as a secret

* Remove debris

* Updates based on personal review

* Add sample

* Fix lint issue

* Improve documentation of CreationMode

* Default CreationMode to AdoptOrCreate

* Add IsAssignableToRole

* Directly support all four kinds of membership

* Default CreationMode via WebHook

* Update test

* Relocate validation

* Fixup move of validation

* Switch to using configmaps

* go mod tidy

* Remove duplicate imports

* Tidy up  test

* Tidy up test

* Fix test

* Address PR feedback

* Add additional fields to redact.

* Update PR

* Use more permissive interface for setting annotations

* Remove unused method

* Remove unused cloudConfig from EntraClientCache

* Remove unused error return

* Extend documentation on MailNickname

* Use helper method to simplify guard clause

* Update sample

Author: theunrepentantgeek

Taskfile.yml

@@ -106,6 +106,14 @@ tasks:
       - task: generator:format-code
       - task: controller:format-code
 
+  go-mod-tidy:
+    desc: Tidy the go.mod files
+    dir : v2
+    cmds:
+      - task: controller:go-mod-tidy
+      - task: asoctl:go-mod-tidy
+      - task: generator:go-mod-tidy
+
   build-docs-site:
     cmds:
       - task: doc:build-site
@@ -171,6 +179,12 @@ tasks:
       - cmd: gofumpt -l -w .
         ignore_error: true # Just in case the code doesn't build
 
+  asoctl:go-mod-tidy:
+    desc: Tidy the go.mod file
+    dir : v2/cmd/asoctl/
+    cmds:
+      - go mod tidy
+      
   asoctl:lint:
     desc: Run {{.ASOCTL_APP}} fast lint checks.
     dir: '{{.ASOCTL_ROOT}}'
@@ -261,6 +275,12 @@ tasks:
       - cmd: gofumpt -l -w .
         ignore_error: true # Just in case the code doesn't build
 
+  generator:go-mod-tidy:
+    desc: Tidy the go.mod file
+    dir : v2/tools/generator
+    cmds:
+      - go mod tidy
+
   generator:lint:
     desc: Run {{.GENERATOR_APP}} lint checks.
     dir: '{{.GENERATOR_ROOT}}'
@@ -319,6 +339,12 @@ tasks:
       - cmd: gofumpt -l -w .
         ignore_error: true # Just in case the code doesn't build
 
+  controller:go-mod-tidy:
+    desc: Tidy the go.mod file
+    dir : v2
+    cmds:
+      - go mod tidy
+
   controller:lint:
     desc: Run lint checks.
     deps: 

v2/api/entra/v1/creation_mode.go

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+package v1
+
+// CreationMode specifies how ASO will try to create the Entra resource.
+// +kubebuilder:validation:Enum=AdoptOrCreate;AlwaysCreate
+type CreationMode string
+
+const (
+	// AlwaysCreate means that ASO will always attempt to create the resource,
+	// without first checking to see whether it already exists.
+	AlwaysCreate CreationMode = "AlwaysCreate"
+
+	// AdoptOrCreate means that ASO will try to adopt an existing resource if it exists,
+	// and can be uniquely identified.
+	// If multiple matches are found, the resource condition will show an error.
+	// If it does not exist, ASO will create a new resource.
+	AdoptOrCreate CreationMode = "AdoptOrCreate"
+)
+
+// AllowsCreation checks if the creation mode allows ASO to create a new resource.
+// All current modes do, but this could change in the future.
+func (cm CreationMode) AllowsCreation() bool {
+	return cm == AlwaysCreate || cm == AdoptOrCreate
+}
+
+// AllowsAdoption checks if the creation mode allows ASO to adopt an existing resource.
+func (cm CreationMode) AllowsAdoption() bool {
+	return cm == AdoptOrCreate
+}

v2/api/entra/v1/doc.go

@@ -0,0 +1,8 @@
+/*
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+*/
+
+// Package v1 contains hand-crafted API Schema definitions for the entra v1 API group
+// +groupName=entra.azure.com
+package v1

v2/api/entra/v1/groupversion_info.go

@@ -0,0 +1,27 @@
+/*
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+*/
+
+// Package v1 contains API Schema definitions for entra data plane APIs
+// +kubebuilder:object:generate=true
+// All object properties are optional by default, this will be overridden when needed:
+// +kubebuilder:validation:Optional
+// +groupName=entra.azure.com
+package v1
+
+import (
+	"k8s.io/apimachinery/pkg/runtime/schema"
+	"sigs.k8s.io/controller-runtime/pkg/scheme"
+)
+
+var (
+	// GroupVersion is group version used to register these objects
+	GroupVersion = schema.GroupVersion{Group: "entra.azure.com", Version: "v1"}
+
+	// SchemeBuilder is used to add go types to the GroupVersionKind scheme
+	SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion}
+
+	// AddToScheme adds the types in this group-version to the given scheme.
+	AddToScheme = SchemeBuilder.AddToScheme
+)

v2/api/entra/v1/securitygroup_types.go

@@ -0,0 +1,216 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+package v1
+
+import (
+	"github.com/microsoftgraph/msgraph-sdk-go/models"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"sigs.k8s.io/controller-runtime/pkg/conversion"
+
+	"github.com/Azure/azure-service-operator/v2/internal/util/to"
+	"github.com/Azure/azure-service-operator/v2/pkg/genruntime"
+	"github.com/Azure/azure-service-operator/v2/pkg/genruntime/conditions"
+)
+
+// +kubebuilder:rbac:groups=entra.azure.com,resources=securitygroups,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups=entra.azure.com,resources={securitygroups/status,users/finalizers},verbs=get;update;patch
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+// +kubebuilder:printcolumn:name="Ready",type="string",JSONPath=".status.conditions[?(@.type=='Ready')].status"
+// +kubebuilder:printcolumn:name="Severity",type="string",JSONPath=".status.conditions[?(@.type=='Ready')].severity"
+// +kubebuilder:printcolumn:name="Reason",type="string",JSONPath=".status.conditions[?(@.type=='Ready')].reason"
+// +kubebuilder:printcolumn:name="Message",type="string",JSONPath=".status.conditions[?(@.type=='Ready')].message"
+// +kubebuilder:storageversion
+// SecurityGroup is an Entra Security Group.
+type SecurityGroup struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+	Spec              SecurityGroupSpec   `json:"spec,omitempty"`
+	Status            SecurityGroupStatus `json:"status,omitempty"`
+}
+
+var _ conditions.Conditioner = &SecurityGroup{}
+
+// GetConditions returns the conditions of the resource
+func (group *SecurityGroup) GetConditions() conditions.Conditions {
+	return group.Status.Conditions
+}
+
+// SetConditions sets the conditions on the resource status
+func (group *SecurityGroup) SetConditions(conditions conditions.Conditions) {
+	group.Status.Conditions = conditions
+}
+
+var _ conversion.Hub = &SecurityGroup{}
+
+// Hub marks that this userSpec is the hub type for conversion
+func (user *SecurityGroup) Hub() {}
+
+// +kubebuilder:object:root=true
+type SecurityGroupList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []SecurityGroup `json:"items"`
+}
+
+type SecurityGroupSpec struct {
+	// DisplayName: The display name of the group.
+	// +kubebuilder:validation:Required
+	DisplayName *string `json:"displayName,omitempty"`
+
+	// MailNickname: The email address of the group, specified either as a mail nickname (`mygroup`)
+	// or as a full email address (`[email protected]`).
+	// +kubebuilder:validation:Required
+	MailNickname *string `json:"mailNickname,omitempty"`
+
+	// Description: The description of the group.
+	Description *string `json:"description,omitempty"`
+
+	// MembershipType: The membership type of the group.
+	MembershipType *SecurityGroupMembershipType `json:"membershipType,omitempty"`
+
+	// OperatorSpec: The operator specific configuration for the resource.
+	OperatorSpec *SecurityGroupOperatorSpec `json:"operatorSpec,omitempty"`
+
+	// IsAssignableToRole: Indicates whether the group can be assigned to a role.
+	IsAssignableToRole *bool `json:"isAssignableToRole,omitempty"`
+}
+
+// OriginalVersion returns the original API version used to create the resource.
+func (spec *SecurityGroupSpec) OriginalVersion() string {
+	return GroupVersion.Version
+}
+
+// AssignToGroup configures the provided instance with the details of the group
+func (spec *SecurityGroupSpec) AssignToGroup(model models.Groupable) {
+	model.SetSecurityEnabled(to.Ptr(true))
+	model.SetDisplayName(spec.DisplayName)
+
+	if spec.MailNickname != nil {
+		model.SetMailNickname(spec.MailNickname)
+	}
+
+	if spec.Description != nil {
+		model.SetDescription(spec.Description)
+	}
+
+	// Set the membership type
+	membershipType := SecurityGroupMembershipTypeAssigned
+	if spec.MembershipType != nil {
+		membershipType = *spec.MembershipType
+	}
+
+	var groupTypes []string
+	switch membershipType {
+	case SecurityGroupMembershipTypeAssigned:
+	// Empty list means assigned membership
+	case SecurityGroupMembershipTypeAssignedM365:
+		groupTypes = []string{"Unified"}
+	case SecurityGroupMembershipTypeDynamic:
+		groupTypes = []string{"DynamicMembership"}
+	case SecurityGroupMembershipTypeDynamicM365:
+		groupTypes = []string{"Unified", "DynamicMembership"}
+	}
+	model.SetGroupTypes(groupTypes)
+
+	// Set isAssignableToRole
+	if spec.IsAssignableToRole != nil {
+		model.SetIsAssignableToRole(spec.IsAssignableToRole)
+	}
+
+	// This is a security group, not a mail distribution group
+	model.SetMailEnabled(to.Ptr(false))
+}
+
+type SecurityGroupStatus struct {
+	// EntraID: The GUID identifing the resource in Entra
+	EntraID *string `json:"entraID,omitempty"`
+
+	// DisplayName: The display name of the group.
+	DisplayName *string `json:"displayName,omitempty"`
+
+	// Conditions: The observed state of the resource
+	Conditions []conditions.Condition `json:"conditions,omitempty"`
+
+	// +kubebuilder:validation:Required
+	// MailNickname: The email address of the group.
+	MailNickname *string `json:"groupEmailAddress,omitempty"`
+
+	// Description: The description of the group.
+	Description *string `json:"description,omitempty"`
+}
+
+func (status *SecurityGroupStatus) AssignFromGroup(model models.Groupable) {
+	if id := model.GetId(); id != nil {
+		status.EntraID = id
+	}
+
+	if name := model.GetDisplayName(); name != nil {
+		status.DisplayName = name
+	}
+
+	if mailNickname := model.GetMailNickname(); mailNickname != nil {
+		status.MailNickname = mailNickname
+	}
+
+	if description := model.GetDescription(); description != nil {
+		status.Description = description
+	}
+}
+
+// +kubebuilder:validation:Enum={"assigned","enabled","assignedm365","enabledm365"}
+// +kubebuilder:default=AdoptOrCreate
+type SecurityGroupMembershipType string
+
+const (
+	// SecurityGroupMembershipTypeAssigned indicates that the group is a security group with assigned members.
+	SecurityGroupMembershipTypeAssigned SecurityGroupMembershipType = "assigned"
+	// SecurityGroupMembershipTypeDynamic indicates that the group is a security group with dynamic membership.
+	SecurityGroupMembershipTypeDynamic SecurityGroupMembershipType = "dynamic"
+	// SecurityGroupMembershipTypeAssigned indicates that the group is a Microsoft 365 security group with assigned members.
+	SecurityGroupMembershipTypeAssignedM365 SecurityGroupMembershipType = "assignedm365"
+	// SecurityGroupMembershipTypeDynamic indicates that the group is a Microsoft 365 security group with dynamic membership.
+	SecurityGroupMembershipTypeDynamicM365 SecurityGroupMembershipType = "dynamicm365"
+)
+
+type SecurityGroupOperatorSpec struct {
+	// CreationMode: Specifies how ASO will try to create the resource.
+	// Specify "AlwaysCreate" to always create a new security group when first reconciled.
+	// Or specify "AdoptOrCreate" to first try to adopt an existing security group with the same display name.
+	// If multiple security groups with the same display name are found, the resource condition will show an error.
+	// If not specified, defaults to "AdoptOrCreate".
+	CreationMode *CreationMode `json:"creationMode,omitempty"`
+
+	// ConfigMaps specifies any config maps that should be created by the operator.
+	ConfigMaps *SecurityGroupOperatorConfigMaps `json:"configmaps,omitempty"`
+}
+
+// CreationAllowed checks if the creation mode allows ASO to create a new security group.
+func (spec *SecurityGroupOperatorSpec) CreationAllowed() bool {
+	if spec.CreationMode == nil {
+		// Default is AdoptOrCreate
+		return true
+	}
+
+	return spec.CreationMode.AllowsCreation()
+}
+
+// AllowsAdoption checks if the creation mode allows ASO to adopt an existing security group.
+func (spec *SecurityGroupOperatorSpec) AdoptionAllowed() bool {
+	if spec.CreationMode == nil {
+		// Default is AdoptOrCreate
+		return true
+	}
+
+	return spec.CreationMode.AllowsAdoption()
+}
+
+type SecurityGroupOperatorConfigMaps struct {
+	// EntraID: The Entra ID of the group.
+	EntraID *genruntime.ConfigMapDestination `json:"entraID,omitempty"`
+}
+
+func init() {
+	SchemeBuilder.Register(&SecurityGroup{}, &SecurityGroupList{})
+}