Documentation ¶
Index ¶
- Constants
- type Container
- type ContainerType
- type HierarchicalReference
- type HierarchicalReferenceType
- type IAMConfig
- type IAMMemberReferenceConfig
- type IAMReferenceField
- type IAMReferenceType
- type MetadataMapping
- type ReferenceConfig
- type ResourceConfig
- type ResourceID
- type ResourceReference
- type SecretKeyReference
- type SensitiveField
- type ServiceMapping
- type ServiceMappingList
- type ServiceMappingSpec
- type TypeConfig
- type ValueSource
Constants ¶
const ( ContainerTypeProject = "project" ContainerTypeFolder = "folder" ContainerTypeOrganization = "organization" )
The following constants are the valid container types.
const ( HierarchicalReferenceTypeProject = HierarchicalReferenceType("project") HierarchicalReferenceTypeFolder = HierarchicalReferenceType("folder") HierarchicalReferenceTypeOrganization = HierarchicalReferenceType("organization") HierarchicalReferenceTypeBillingAccount = HierarchicalReferenceType("billingAccount") )
The following constants are the valid hierarchical reference types.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Container ¶
type Container struct { // Type is the type of container this represents. Type ContainerType `json:"type"` // TFField is the path to the field in the underlying Terraform provider that // represents the implicit reference to the container object. Use periods to delimit // the fields in the path. For example, if the field is "bar" nested inside "foo" ("foo" // being either an object or a list of objects), the associated TFField should be // "foo.bar") TFField string `json:"tfField"` // ValueTemplate is a template by which the value of the container annotation // should be interpreted before being passed to the Terraform provider. {{value}} // is used in place of this sourced value. // // e.g. If the value sourced from the container annotation is "123456789", a // valueTemplate of "folders/{{value}}" would mean the final value passed to the // provider is "folders/123456789" ValueTemplate string `json:"valueTemplate,omitempty"` }
func (*Container) DeepCopy ¶
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new Container.
func (*Container) DeepCopyInto ¶
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type ContainerType ¶
type ContainerType string
type HierarchicalReference ¶
type HierarchicalReference struct { // Type is the type of hierarchical reference that this hierarchical // reference configuration represents. Type HierarchicalReferenceType `json:"type"` // Key is the field name of the resource reference that this hierarchical // reference configuration corresponds to (e.g. "projectRef"). It is // assumed that all resource references marked as hierarchical references // are located at the root-level of the spec. Key string `json:"key"` }
func (*HierarchicalReference) DeepCopy ¶
func (in *HierarchicalReference) DeepCopy() *HierarchicalReference
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HierarchicalReference.
func (*HierarchicalReference) DeepCopyInto ¶
func (in *HierarchicalReference) DeepCopyInto(out *HierarchicalReference)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type HierarchicalReferenceType ¶
type HierarchicalReferenceType string
type IAMConfig ¶
type IAMConfig struct { // PolicyName is the terraform name of the associated IAM Policy resource (e.g. google_spanner_instance_iam_policy) PolicyName string `json:"policyName"` // PolicyMemberName is the terraform name of the associated IAM Policy Member resource (e.g. google_spanner_instance_iam_member) PolicyMemberName string `json:"policyMemberName"` // AuditConfigName is the terraform name of the associated IAM Audit Config resource, if there is any (e.g. google_project_iam_audit_config for the Project resource) AuditConfigName string `json:"auditConfigName,omitempty"` // A description of the manner in which the IAM Policy references its resource. ReferenceField IAMReferenceField `json:"referenceField,omitempty"` // SupportsConditions indicates whether or not the resource supports IAM Conditions. SupportsConditions bool `json:"supportsConditions"` }
func (*IAMConfig) DeepCopy ¶
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new IAMConfig.
func (*IAMConfig) DeepCopyInto ¶
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type IAMMemberReferenceConfig ¶
type IAMMemberReferenceConfig struct { // TargetField is the referenced resource's Terraform field that will be // extracted and used as a member identity. For example, a LoggingLogSink's // writer identity can be referenced by setting TargetField to // "writer_identity", a field defined on the google_logging_log_sink // resource. TargetField string `json:"targetField"` // ValueTemplate is a template by which the value sourced from the reference should // be interpreted before being used as a member identity. {{value}} is used // in place of this sourced value. The template can contain other value placeholders // that need to be sourced from the reference resource. // // e.g. If the value sourced from the reference is "foo@domain.com", a // valueTemplate of "serviceAccount:{{value}}" would mean the final value // used as a member identity is "serviceAccount:foo@domain.com" // e.g. If the template is "projects/{{project}}/topics/{{value}}", the // project value will be sourced from the referenced resource. ValueTemplate string `json:"valueTemplate,omitempty"` }
func (*IAMMemberReferenceConfig) DeepCopy ¶
func (in *IAMMemberReferenceConfig) DeepCopy() *IAMMemberReferenceConfig
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new IAMMemberReferenceConfig.
func (*IAMMemberReferenceConfig) DeepCopyInto ¶
func (in *IAMMemberReferenceConfig) DeepCopyInto(out *IAMMemberReferenceConfig)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type IAMReferenceField ¶
type IAMReferenceField struct { // The name of the field in the policy or binding which references the resource. For // 'google_spanner_instance_iam_policy' this value is 'instance'. Name string `json:"name"` // The type of value that should be used in this field. It can be one of { name, id }. For // 'google_spanner_instance_iam_policy' it would be 'name' for 'google_kms_key_ring_iam_policy' // it would be 'id'. Type IAMReferenceType `json:"type"` }
A reference from an IAM policy or binding to a resource.
func (*IAMReferenceField) DeepCopy ¶
func (in *IAMReferenceField) DeepCopy() *IAMReferenceField
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new IAMReferenceField.
func (*IAMReferenceField) DeepCopyInto ¶
func (in *IAMReferenceField) DeepCopyInto(out *IAMReferenceField)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type IAMReferenceType ¶
type IAMReferenceType string
const ( IAMReferenceTypeName IAMReferenceType = "name" IAMReferenceTypeId IAMReferenceType = "id" )
type MetadataMapping ¶
type MetadataMapping struct { // Name is a JSONPath to the field in the TF resource where the KRM "metadata.name" field will be mapped to. By // default, this is mapped to the "name" field, if that field is found in the TF resource schema. Name string `json:"name,omitempty"` // NameValueTemplate is a template by which the value of the metadata.name field // should be interpreted before being passed to the Terraform provider. {{value}} // is used in place of this sourced value. // // e.g. If the value sourced from metadata.name is "foo_bar", a nameValueTemplate of // "resource/{{value}}" would mean the final value passed to the provider is // "resource/foo_bar" NameValueTemplate string `json:"nameValueTemplate,omitempty"` // Labels is a JSONPath to the field in the TF resource where the KRM "metadata.labels" field will be mapped to. By // default, this is mapped to the "labels" field, if that field is found in the TF resource schema. Labels string `json:"labels,omitempty"` }
func (*MetadataMapping) DeepCopy ¶
func (in *MetadataMapping) DeepCopy() *MetadataMapping
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new MetadataMapping.
func (*MetadataMapping) DeepCopyInto ¶
func (in *MetadataMapping) DeepCopyInto(out *MetadataMapping)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type ReferenceConfig ¶
type ReferenceConfig struct { // The inlined type configuration for this reference. Must not be filled // out if Types is set. TypeConfig `json:",inline"` // TFField is the path to the field in the underlying Terraform provider that is // the implicit reference. Use periods to delimit the fields in the path. For // example, if the reference field is "bar" nested inside "foo" ("foo" being // either an object or a list of objects), the associated TFField should be // "foo.bar") TFField string `json:"tfField"` // Description is the description for the resource reference that will be // exposed in the CRD. Description string `json:"description,omitempty"` // Types is the supported types this resource reference supports. Must not // be specified if the inlined TypeConfig is filled out. // // If the value for the reference is not specified in the KRM spec, it is // possible that a default value may be set by GCP. This default reference // value will be populated in the KRM resource's spec. In cases where a // resource reference has multiple types, the first type in this list will // become the default TypeConfig for that value. Types []TypeConfig `json:"types,omitempty"` }
func (*ReferenceConfig) DeepCopy ¶
func (in *ReferenceConfig) DeepCopy() *ReferenceConfig
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ReferenceConfig.
func (*ReferenceConfig) DeepCopyInto ¶
func (in *ReferenceConfig) DeepCopyInto(out *ReferenceConfig)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type ResourceConfig ¶
type ResourceConfig struct { // Name is the Terraform name of the resource (e.g. google_spanner_instance) Name string `json:"name"` // Kind is the Kubernetes kind you wish the resource to have. Kind string `json:"kind"` // SkipImport skips the import step when fetching the live state of the underlying // resource. If specified, IDTemplate must also be specified, and its expanded // form will be used as the TF resource's `id` field. SkipImport bool `json:"skipImport,omitempty"` // IAMConfig contains the mappings from a given resource onto its associated terraform IAM resources (policies, bindings, and members) IAMConfig IAMConfig `json:"iamConfig,omitempty"` // IAMMemberReferenceConfig configures the resource as a resource that can // be referenced as an IAM member. IAMMemberReferenceConfig IAMMemberReferenceConfig `json:"iamMemberReferenceConfig,omitempty"` // IDTemplate defines the format in which the ID fed into the TF resource's importer // should look. Fields may be sourced from the TF resource by using the `{{foo}}` // syntax. (e.g. {{project}}/{{location}}/{{name}}. // // All fields are required. A field can be marked as optional with the ? suffix, e.g. with {{project}}/{{host?}}, // the host field is optional // // An OR condition can be defined on a portion of the template by enclosing the portion with brackets `[...]` and using // a bar character, `|`, to deliminate the OR. Example, `my-template/[{{field1}}|text_{{field2}]`. // // If SkipImport is true, this must be specified, and its expanded form will be directly // used as the TF resource's `id` field. IDTemplate string `json:"idTemplate,omitempty"` // The resource name is the One Platform / GCP resource name, when this value is true, it means the IDTemplate // can be converted to a regex and used to match against a given URL to determine if it is a name for the given // ResourceConfig. If this flag is true then the ID Template is used by "config-connector export" to match against // URLs. // // see: https://cloud.google.com/apis/design/resource_names IDTemplateCanBeUsedToMatchResourceName *bool `json:"idTemplateCanBeUsedToMatchResourceName,omitempty"` // ServerGeneratedIDField is the field in the resource's status that corresponds to // the server-generated resource ID. If unset, it's assumed the resource ID is specified // by the user. Resources with this set do not support acquisition. ServerGeneratedIDField string `json:"serverGeneratedIDField,omitempty"` // Locationality categorizes the GCP resources as global, regional, or zonal. It's only applicable to the effort of // unifying multiple locational TF resources into one, e.g. KCC could have a single ComputeAddress CRD to represent // two TF/GCE resources - compute address and global compute address. The location field in ComputeAddress CRD is used to specify // whether it is a global address or regional address. If unset, it's assumed that there is no multiple TF locational resources // mapping to the same compute resource schema. Currently, this supports the following values: global, regional, zonal. Locationality string `json:"locationality,omitempty"` // MetadataMapping determines how to map Kubernetes metadata fields to the Terraform // resource's configuration. MetadataMapping MetadataMapping `json:"metadataMapping,omitempty"` // ResourceID determines how to map the `spec.resourceID` field to the // Terraform resource's configuration. // For multiple ResourceConfigs that map to the same Kind, their ResourceID // definition must be the same. ResourceID ResourceID `json:"resourceID,omitempty"` // ResourceReferences configures the mapping of fields in the Terraform resource that // implicitly define references to other GCP resources into explicit Kubernetes-style // references. ResourceReferences []ReferenceConfig `json:"resourceReferences,omitempty"` // Directives is a list of Terraform fields that perform unique behaviors on // top of the resource which are not part of a GET response. If the KCC annotation's // key contains a directive from this list (e.g. `cnrm.cloud.google.com/force-destroy`), // the value from the annotation is stored/overwritten in the TF config (e.g. force_destroy -> true) Directives []string `json:"directives,omitempty"` // MutableButUnreadableFields is a list of Terraform fields that are // mutable but not returned by the Terraform read. KCC tracks the values of // such fields to be able to determine if the user changed their values on // the spec. MutableButUnreadableFields []string `json:"mutableButUnreadableFields,omitempty"` // IgnoredFields is a list of fields that should be dropped from the underlying // Terraform resource. IgnoredFields []string `json:"ignoredFields,omitempty"` // Deprecated: use HierarchicalReferences instead. Only resources that // already specify Containers should continue to specify Containers so that // these resources can continue to support resource-level container // annotations. Since new resources should not support resource-level // container annotations, they should not specify Containers. // // Containers describes all the container mappings this resource understands. Config Connector maps Kubernetes // namespaces to the abstract GCP container objects they are scoped by via namespaces. For most resource types, // this is a project, but certain resources live outside the scope of a project, like folders or projects // themselves. Containers are expressed as annotations on a given Namespace, though users may provide // resource-level overrides. Containers []Container `json:"containers,omitempty"` // HierarchicalReferences lists the resource references that represent // references to hierarchical resources (e.g. project, folder, // organization). HierarchicalReferences []HierarchicalReference `json:"hierarchicalReferences,omitempty"` // ResourceAvailableInAssetInventory specifies if the resource exists in asset inventory // visible here: https://cloud.google.com/asset-inventory/docs/supported-asset-types#supported_resource_types ResourceAvailableInAssetInventory bool `json:"resourceAvailableInAssetInventory,omitempty"` // AutoGenerated indicates whether the resource is generated automatically // via the KCC resource auto-generation process. // A ResourceConfig should not set this field to 'true' unless it is // generated via auto generation. AutoGenerated bool `json:"autoGenerated,omitempty"` // ReconciliationIntervalInSeconds specifies the default mean reconciliation interval for this resource. // Providing the value in servicemapping config is optional. If not explicity configured a global // default value of 600 will be used ReconciliationIntervalInSeconds *uint32 `json:"reconciliationIntervalInSeconds,omitempty"` }
func (*ResourceConfig) DeepCopy ¶
func (in *ResourceConfig) DeepCopy() *ResourceConfig
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ResourceConfig.
func (*ResourceConfig) DeepCopyInto ¶
func (in *ResourceConfig) DeepCopyInto(out *ResourceConfig)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type ResourceID ¶
type ResourceID struct { // TargetField is the name of the field in the TF resource where the KRM // `spec.resourceID` field will be mapped to. TargetField string `json:"targetField,omitempty"` // ValueTemplate is a template by which the value of the `spec.resourceID` // field should be interpreted before being passed to the Terraform // provider. // {{value}} is used in place of the source value, i.e. the value of // `spec.resourceID`. // // E.g. If `spec.resourceID` is "foo", a ValueTemplate of // "resources/{{value}}" means the final value passed to the Terraform // provider is "resources/foo". ValueTemplate string `json:"valueTemplate,omitempty"` }
func (*ResourceID) DeepCopy ¶
func (in *ResourceID) DeepCopy() *ResourceID
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ResourceID.
func (*ResourceID) DeepCopyInto ¶
func (in *ResourceID) DeepCopyInto(out *ResourceID)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type ResourceReference ¶
type ResourceReference struct { Namespace string `json:"namespace,omitempty"` Name string `json:"name,omitempty"` External string `json:"external,omitempty"` }
ResourceReference defines a relationship to another resource
func (*ResourceReference) DeepCopy ¶
func (in *ResourceReference) DeepCopy() *ResourceReference
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ResourceReference.
func (*ResourceReference) DeepCopyInto ¶
func (in *ResourceReference) DeepCopyInto(out *ResourceReference)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type SecretKeyReference ¶
type SecretKeyReference struct { Name string `json:"name,omitempty"` Key string `json:"key,omitempty"` }
SecretKeyReference represents a relationship to a keyed value in a Secret object
func (*SecretKeyReference) DeepCopy ¶
func (in *SecretKeyReference) DeepCopy() *SecretKeyReference
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new SecretKeyReference.
func (*SecretKeyReference) DeepCopyInto ¶
func (in *SecretKeyReference) DeepCopyInto(out *SecretKeyReference)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type SensitiveField ¶
type SensitiveField struct { Value *string `json:"value,omitempty"` ValueFrom *ValueSource `json:"valueFrom,omitempty"` }
SensitiveField represents a field that expects sensitive information (e.g. passwords)
func (*SensitiveField) DeepCopy ¶
func (in *SensitiveField) DeepCopy() *SensitiveField
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new SensitiveField.
func (*SensitiveField) DeepCopyInto ¶
func (in *SensitiveField) DeepCopyInto(out *SensitiveField)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type ServiceMapping ¶
type ServiceMapping struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` // ServiceMappingSpec defines the aspects common to all resources of a particular // service being mapped from the Terraform provider to Kubernetes Resource Model (KRM). Spec ServiceMappingSpec `json:"spec,omitempty"` }
ServiceMapping is configuration mapping Terraform resources to Kubernetes Resource Model (KRM). It is used both during initial CRD generation as well as calling the Terraform provider at runtime. +k8s:openapi-gen=true
func (*ServiceMapping) DeepCopy ¶
func (in *ServiceMapping) DeepCopy() *ServiceMapping
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ServiceMapping.
func (*ServiceMapping) DeepCopyInto ¶
func (in *ServiceMapping) DeepCopyInto(out *ServiceMapping)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
func (*ServiceMapping) DeepCopyObject ¶
func (in *ServiceMapping) DeepCopyObject() runtime.Object
DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.
type ServiceMappingList ¶
type ServiceMappingList struct { metav1.TypeMeta `json:",inline"` metav1.ListMeta `json:"metadata,omitempty"` Items []ServiceMapping `json:"items"` }
ServiceMappingList contains a list of ServiceMapping
func (*ServiceMappingList) DeepCopy ¶
func (in *ServiceMappingList) DeepCopy() *ServiceMappingList
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ServiceMappingList.
func (*ServiceMappingList) DeepCopyInto ¶
func (in *ServiceMappingList) DeepCopyInto(out *ServiceMappingList)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
func (*ServiceMappingList) DeepCopyObject ¶
func (in *ServiceMappingList) DeepCopyObject() runtime.Object
DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.
type ServiceMappingSpec ¶
type ServiceMappingSpec struct { // Name is the name of the service being mapped (e.g. Spanner, PubSub). This is // used for the construction of the generated CRDs' API group and kind. Name string `json:"name"` // Version is the API version for all the resource CRDs being generated. Version string `json:"version"` // ServiceHostName is the host portion of the URL for the associated service. IE, for Spanner, it is 'spanner.googleapis.com' ServiceHostName string `json:"serviceHostName"` // Resources is a list of configurations specifying how to map a specific resource // from the Terraform provider to KRM. Resources []ResourceConfig `json:"resources"` }
func (*ServiceMappingSpec) DeepCopy ¶
func (in *ServiceMappingSpec) DeepCopy() *ServiceMappingSpec
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ServiceMappingSpec.
func (*ServiceMappingSpec) DeepCopyInto ¶
func (in *ServiceMappingSpec) DeepCopyInto(out *ServiceMappingSpec)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type TypeConfig ¶
type TypeConfig struct { // Key is the field name that will be exposed through the KRM resource's spec. It // should follow the Kubernetes reference naming semantics: // `fooRef`, where foo is some describer of what is being referenced (e.g. // instanceRef, healthCheckRef) // Complex references (those with a "Types" list defined) or lists of references // should not specify a key. Key string `json:"key,omitempty"` // TargetField is the referenced resource's Terraform field that will // be extracted and set as the value of the TFField. For example, a // ComputeSubnetwork can reference a ComputeNetwork's self link by // setting TargetField to "self_link", a field defined on the // google_compute_network resource. TargetField string `json:"targetField,omitempty"` // GVK is the Group,Version,Kind of the resource being referenced. // // This field is mutually exclusive with JSONSchemaType. GVK schema.GroupVersionKind `json:"gvk,omitempty"` // Parent specifies whether the referenced resource is a parent. If the parent // is successfully deleted, this resource may be deleted without any call to the // underlying API. Only one parent may be present. A parent reference's TFField // must not be a nested path. Parent bool `json:"parent,omitempty"` // JSONSchemaType specifies the type as understood by JSON schema validation of this // reference field. Should never be specified for a TypeConfig inlined in the // ReferenceConfig. // // This field is mutually exclusive with Kind and TargetField. JSONSchemaType string `json:"jsonSchemaType,omitempty"` // ValueTemplate is a template by which the value sourced from the reference should // be interpreted before being passed to the Terraform provider. {{value}} is used // in place of this sourced value. The template can contain other value placeholders // that need to be sourced from the reference resource. // // e.g. If the value sourced from the reference is "foo@domain.com", a valueTemplate // of "serviceAccount:{{value}}" would mean the final value passed to the provider // is "serviceAccount:foo@domain.com" // e.g. If the template is "projects/{{project}}/topics/{{value}}", the project value // will be sourced from the referenced resource. ValueTemplate string `json:"valueTemplate,omitempty"` }
func (*TypeConfig) DeepCopy ¶
func (in *TypeConfig) DeepCopy() *TypeConfig
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new TypeConfig.
func (*TypeConfig) DeepCopyInto ¶
func (in *TypeConfig) DeepCopyInto(out *TypeConfig)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
type ValueSource ¶
type ValueSource struct {
SecretKeyRef *SecretKeyReference `json:"secretKeyRef,omitempty"`
}
ValueSource represents a source for the value of a SensitiveField
func (*ValueSource) DeepCopy ¶
func (in *ValueSource) DeepCopy() *ValueSource
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ValueSource.
func (*ValueSource) DeepCopyInto ¶
func (in *ValueSource) DeepCopyInto(out *ValueSource)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.