Práticas recomendadas de configuração

Este artigo fornece orientações para melhor gerir os requisitos de configuração da função de rede utilizando o Azure Operator Service Manager. Isto inclui o desenho de esquemas de grupos de configuração ótimos (CGSs), valores de grupos de configuração (CGVs) e modelos de recursos networkFunctions (NFs). Tenha estas práticas em mente ao integrar e implementar NFs.

Abordagem de configuração

Considere as seguintes diretrizes para meta-esquemas ao desenhar recursos de configuração:

• Primeiro, escolha quais os parâmetros a expor ao operador.
  • Uma regra prática é expor parâmetros suportados por operação direta, como um helm value.
  • Suprimir parâmetros suportados por outro agente, como cloudinit userdata.
• Organize os parâmetros em conjuntos específicos de site, de instância e de segurança.
  • Assegura-te de que os parâmetros não se sobrepõem entre conjuntos.
• Defina parâmetros obrigatórios versus opcionais.
  • Para parâmetros opcionais, defina um valor padrão razoável.
• Para evitar a exposição de segredos, assegure a configuração adequada dos parâmetros específicos de segurança.

Abordagem One-CGS

A recomendação original era utilizar apenas um único conjunto CGS/CGV para a NF inteira. Esta abordagem consolidou, em conjunto, os parâmetros específicos: do local, da instância e da segurança. Apenas em casos raros, quando um serviço tinha múltiplos NFs, eram usados vários conjuntos. Muitos parceiros conseguiram integrar com sucesso esta abordagem, e esta continua a ser suportada. No entanto, esta abordagem não obscurece segredos. Todos os valores de configuração são armazenados em texto simples e podem ser exibidos através da maioria dos métodos Azure.

Abordagem Three-CGS

Recomendamos agora que utilize pelo menos três conjuntos CGS/CGV, organizando os parâmetros da seguinte forma:

• Parâmetros específicos do sitio

  • Exemplos incluem endereços IP e nomes únicos.
  • Usa CGS/CGV sem segredos.
  • Armazena os valores em texto simples durante as implementações.

• Parâmetros específicos de instância

  • Exemplos incluem tempos limite e níveis de depuração.
  • Usa CGS/CGV sem segredos.
  • Armazena os valores em texto simples durante a implementação.

• Parâmetros específicos de segurança

  • Exemplos incluem palavras-passe e certificados.
  • Usa CGS/CGV com segredos.
  • Armazenar valores no Azure Key Vault (AKV) para obscurecer durante as implementações.

CGS sem segredos

Este exemplo mostra um CGS expondo abc, xyz, e qwe parâmetros. Dois dos parâmetros têm valores predefinidos e um está marcado como obrigatório.

{ 
  "type": "object", 
  "properties": {
    "abc": { 
      "type": "integer", 
      "default": 30
    }, 
    "xyz": { 
      "type": "integer", 
      "default": 40
    },
    "qwe": {
      "type": "integer"
    }
   }
   "required": "qwe"
}

CGV sem segredos

Este exemplo mostra a entrada CGV fornecida pelo operador durante a implementação do CGV de forma a cumprir o CGS anterior.

{
"qwe": 20
}

Este exemplo mostra o recurso CGV renderizado criado após a conclusão da implementação do CGV.

{
"abc": 30,
"xyz": 40,
"qwe": 20
}

CGV com segredos sem AKV

Quando o AKV não está a ser utilizado, considere os seguintes requisitos do modelo Azure Resource Manager (ARM) para ocultar corretamente os valores secretos ao longo do ciclo de vida dos recursos CGV.

• Para conter todos os segredos, defina-se um parâmetro de objeto com "type": "secureObject".
  • Esta configuração obscurece a apresentação de segredos como parâmetros de modelo.

Este exemplo mostra como definir um parâmetro secretCgvContentde objeto .

"parameters": {
   "secretCgvContent": {
     "type": "SecureObject"
    }
}

• Nas propriedades de recursos CGV, utilize configurationType: 'Secret' e "secretConfigurationValue": "[string(parameters('secretCgvContent'))]".
  • Esta configuração impede que os dados secretos sejam exibidos através da maioria das interfaces de utilizador do Azure.

Este exemplo mostra como passar todos os segredos do objeto secretCgvContent para o recurso CGV.

{
  "type": "Microsoft.HybridNetwork/configurationGroupValues",
  "properties": {
    "configurationType": "Secret"
    "secretConfigurationValue": "[string(parameters('secretCgvContent'))]"
  }
}

CGV com segredos com AKV

Quando o AKV está a ser utilizado, considere os seguintes requisitos do modelo ARM para ocultar corretamente os valores secretos ao longo do ciclo de vida dos recursos CGV.

• Defina uma string parameter para cada segredo e um objeto variable para recolher todos os valores secretos.
  • A variável objeto contém apenas uma referência à cadeia de parâmetros.

Este exemplo mostra como definir um parâmetro secretPassword1 contido na variável secretVal.configurationValueobjeto .

"parameters": {
   "secretPassword1": {
     "type": "string"
    }
}
"variables": {
    "configurationValue": {
     "secretVal": {
        "elastic_passwd": "secretPassword1"
      }
    }
}

• Para entrada de parâmetros, use uma referência de modelo para o AKV em vez do segredo em texto simples.
  • Esta configuração obscurece a apresentação dos segredos como variáveis modelo.

Este exemplo mostra como definir o segredo secretPassword1 usando o segredo e a chave AKV.

  "secretPassword1": {
      "reference": {
        "keyVault": {
            "id": "/subscriptions/xxx/resourceGroups/yyy/providers/Microsoft.KeyVault/vaults/zz"
        },
        "secretPassword1": "<akv-secret-key>"
      }
}

• Nas propriedades de recursos CGV, utilize configurationType: 'Secret' e "secretConfigurationValue": "string(secretVal.configurationValue)".
  • Esta configuração impede que os dados secretos sejam exibidos através da maioria das interfaces de utilizador do Azure.

Este exemplo mostra como passar todos os segredos do objeto secretVal.configurationValue para o novo CGV.

{
"resources": [ {
  "type": "Microsoft.HybridNetwork/configurationGroupValues",
    "properties": {
      "configurationType": "Secret"
      "secretConfigurationValue": "string(secretVal.configurationValue)"
      }
   }
]

networkFunctions com segredos

Considere os seguintes requisitos do modelo ARM para ocultar corretamente os valores secretos ao longo do ciclo de vida dos recursos networkFunctions.

• Use "type": "secureObject" no modelo para os parâmetros secretValues e config
  • Esta configuração obscurece a apresentação dos segredos como parâmetros do modelo.

"parameters": {
    "nfValues": {
     "type": "object"
    },
    "siteSpecificValues": {
     "type": "object"
    },
    "secretValues": {
     "type": "secureObject"
    },
    "config": {
      "type": "secureObject",
      "defaultValue": "[union(parameters('nfValues'), parameters('siteSpecificValues'), parameters('secretValues'))]"
    }
}

• Nas propriedades de recursos do networkFunctions, use configurationType: 'Secret' e "secretDeploymentValues": "[string(parameters('config'))]".
  • Uma vez implementada uma função de rede, esta configuração impede a exibição dos dados secretos através da maioria das interfaces de utilizador do Azure.

"resources": [
  {
    "type": "Microsoft.HybridNetwork/networkFunctions",
      "configurationType": "Secret",
      "secretDeploymentValues": "[string(parameters('config'))]",
  }
]

Visão geral do Esquema JSON

JSON Schema é um standard da Internet Engineering Task Force (IETF) que fornece um formato para quais dados JSON são necessários para uma aplicação e como interagir com eles. Aplicar tais padrões a um documento JSON ajuda-o a garantir consistência e validade dos dados em todos os dados JSON.

Onde é utilizado o esquema JSON?

• Azure Operator Service Manager usa a notação de esquema JSON como um meta-esquema nas propriedades schemaDefinition do objeto CGS ConfigurationGroupSchemaPropertiesFormat.
• O Azure Operator Service Manager permite ao designer e ao editor especificar o Esquema JSON quando o operador deve fornecer dados (valores JSON) durante a instância de um serviço de rede de site (SNS) ou NF.
• O Azure Operator Service Manager permite que as propriedades do meta-esquema sejam opcionais ou obrigatórias. Quando uma propriedade está marcada required, deve ser especificada nos valores JSON.

Quais palavras-chave JSON são suportadas?

Para o meta-esquema CGS, o Azure Operator Service Manager implementa suporte para palavras-chave padrão JSON tipo a tipo:

• Para tipos de objetos, o suporte a palavras-chave é limitado pela política de filtros. Ver objeto na referência do Esquema JSON.
• Para tipos de cadeia de caracteres, o suporte a palavras-chave não é limitado ou filtrado. Veja string na referência do JSON Schema.
• Para tipos numéricos, o suporte a palavras-chave não é limitado ou filtrado. Ver Tipos numéricos na referência do Esquema JSON.

Campos opcionais e obrigatórios

Declara uma propriedade como opcional ao incluir uma required palavra-chave, que omite a propriedade opcional. Se não especificar a required palavra-chave, todas as propriedades são consideradas necessárias. Precisa de pelo menos um tipo de propriedade obrigatório para dar suporte a um tipo de propriedade opcional.

{
"type": "object",
"properties": {
  "abc": {
    "type": "integer",
     "default": 30
  },
  "xyz": {
    "type": "string",
    "default": "abc123"
  }
 }
"required":  ["abc"]
} 

Valores padrão no Esquema JSON

Para propriedades opcionais, o Azure Operator Service Manager implementa um método personalizado para gerir valores predefinidos. Quando um valor por defeito é definido no meta-esquema CGS, o Azure Operator Service Manager utiliza esse valor quando a propriedade está em falta ou não está definida nos dados CGV de entrada. A lógica do validador Azure Operator Service Manager basicamente hidrata o valor CGV com o valor padrão quando o operador não fornece um valor.

Como definir padrões

Os valores padrão devem ser especificados dentro das propriedades ou dentro dos elementos de um array. O exemplo seguinte demonstra valores predefinidos com tipos de propriedades inteiras e de cadeia de caracteres:

{
"type": "object",
"properties": {
  "abc": {
    "type": "integer",
     "default": 30
  },
  "xyz": {
    "type": "string",
    "default": "abc123"
  }
 }
} 

Regras para definir padrões

As seguintes regras são aplicadas quando está a validar um valor padrão. Considere estas regras quando estiver a usar valores padrão para garantir os resultados esperados.

• Um valor padrão não deve ser aplicado a uma propriedade necessária.
• Um valor padrão é avaliado por ordem top-down a partir do local onde a palavra-chave aparece pela primeira vez.
• Quando existe um valor de propriedade na entrada do CGV, apenas as subpropriedades dessas propriedades são avaliadas para valores predefinidos.
• Quando não existe valor de propriedade no CGV de entrada, é avaliado um padrão, juntamente com quaisquer filhos.
• Quando um valor de propriedade é o object tipo, e a sua chave não existe no CGV de entrada, não são avaliados os valores padrão para o objeto.